Переход на новый SDK Google Mobile Ads C++

УСТАРЕВШИЙ: Google Mobile Ads C++ SDK устарел с 17 июня 2024 года и не должен использоваться в проектах, которые его еще не используют. Он войдет в режим End-of-Maintenance (EoM) 17 июня 2025 года. Обратите внимание, что версии SDK, выпущенные до даты EoM, продолжат работать, но никаких дальнейших исправлений ошибок или изменений после даты EoM выпускаться не будет.

Вместо Google Mobile Ads C++ SDK рассмотрите возможность использования iOS и Android SDK от AdMob . Для получения поддержки обратитесь на технический форум Google Mobile Ads SDK .

Выпуск Firebase C++ SDK v9.1.0 представляет новый Google Mobile Ads C++ SDK.

Google Mobile Ads C++ SDK — это новая поверхность API, которая включает в себя основные изменения, внесенные в Firebase AdMob C++ SDK для iOS и Android в 2021 и 2022 годах, включая удаление устаревших API и новый процесс работы с полноэкранными типами рекламы.

Старый Firebase AdMob C++ SDK ( firebase::admob ) был помечен как устаревший и в дальнейшем не будет получать никаких обновлений или исправлений ошибок.

Как новый Google Mobile Ads C++ SDK ( firebase::gma ), так и старый Firebase AdMob C++ SDK ( firebase::admob ) останутся частью архивов сборки Firebase C++ SDK в течение периода устаревания Firebase AdMob C++ SDK.

Удаление устаревшего API

Следующие API были полностью удалены из Google Mobile Ads C++ SDK.

RewardedVideoAd

Пространство имен RewardedVideoAd AdMob было заменено классом RewardedAd . RewardedAd ведет себя аналогично InterstitialAd , но включает дополнительный RewardedAdListener для получения уведомлений о наградах за предметы.

NativeExpressAds

NativeExpressAd от AdMob уже был отмечен как устаревший в каждом Firebase AdMob C++ SDK. Поэтому NativeExpressAd не включен в новый Google Mobile Ads C++ SDK.

Изменение пространства имен SDK

SDK переехал в новое пространство имен и имеет новую структуру каталогов:

Пространство имен firebase::gma

Исходники нового Google Mobile Ads C++ SDK находятся в пространстве имен firebase::gma . Старое пространство имен firebase::admob устарело вместе с Firebase AdMob C++ SDK.

Структура каталога

Заголовочные файлы перемещены в новый каталог внутри архива сборки:

Устаревший Firebase AdMob C++ SDK	Новый SDK Google Mobile Ads C++
include/firebase/admob	include/firebase/gma

Библиотека

Firebase AdMob C++ SDK будет предоставлен как статическая библиотека в архиве сборки Firebase C++ SDK:

iOS

Устаревший Firebase AdMob C++ SDK	Новый SDK Google Mobile Ads C++
firebase_admob.xcframework	firebase_gma.xcframework

андроид

Устаревший Firebase AdMob C++ SDK	Новый SDK Google Mobile Ads C++
libfirebase_admob.a	libfirebase_gma.a

Миграции классов, перечислений и структур

В таблице ниже перечислены конкретные классы, перечисления и структуры, которые были изменены или удалены. Вот сводка:

• BannerView переименован в AdView .
• NativeAdExpressView удален.
• Пространство имен RewardedVideo заменено классом RewardedAd .
• Перечисление и прослушиватели PresentationState удаляются и заменяются прослушивателями AdListener и FullScreenContent .

• Следующие параметры удаляются из параметров конфигурации объявлений в AdRequests :

  • конфигурация идентификаторов тестовых устройств
  • таргетинг рекламы по возрасту

  Вместо этого эти параметры теперь можно настроить в RequestConfiguration , который является глобальной настройкой, влияющей на все последующие загрузки рекламы.

Устаревшее firebase::admob namespace	Новое firebase::gma namespace
AdSizeType (перечисление)	AdSize::Type (перечисление)
BannerView	AdView
BannerView::Listener	AdListener AdViewBoundingBoxListener PaidEventListener
BannerView::Position	AdView::Position
BannerView::PresentationState	Удаленный
ChildDirectedTreatmentState	RequestConfiguration::TagForChildDirectedTreatment
Gender (перечисление)	Удаленный
InterstitialAd::Listener	FullScreenContentListener PaidEventListener
KeyValuePair	Удаленный
NativeExpressAdView	Удаленный
PollableRewardListener	Удаленный
RewardItem	AdReward
RewardedVideoAd (пространство имен)	RewardedAd (класс)
RewardedVideoAd::Listener	FullScreenContentListener PaidEventListener UserEarnedRewardListener
AdMobError (перечисление)	AdErrorCode (перечисление)
RewardItem	AdReward

Инициализация SDK

Каждая функция инициализации Google Mobile Ads C++ SDK немедленно возвращает два индикатора состояния:

• Необязательный выходной параметр сообщает, произошла ли ошибка зависимости до начала процесса инициализации.

• Возвращаемый параметр — это ссылка на firebase::Future . Future содержит результаты асинхронной инициализации адаптеров-посредников на устройстве.

Хотя Google Mobile Ads C++ SDK может быть вызван для загрузки AdMob -обслуживаемых объявлений сразу после возврата функции инициализации, другие рекламные сети не будут обслуживать объявления, пока их соответствующий адаптер посредничества не будет полностью инициализирован. Этот процесс происходит асинхронно. Поэтому, если вы используете посредничество объявлений в своем приложении, мы рекомендуем вам дождаться разрешения Future , прежде чем пытаться загрузить какие-либо объявления.

До

firebase::App* app = ::firebase::App::Create();
firebase::InitResult result = firebase::admob::Initialize(*app, kAdMobAppID);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

После

using firebase::App;
using firebase::Future;
using firebase::gma::AdapterInitializationStatus;

App* app = ::firebase::App::Create();
firebase::InitResult result;
Future<AdapterInitializationStatus> future =
  firebase::gma::Initialize(*app, &result);

if (result != kInitResultSuccess) {
  // Initialization immediately failed, most likely due to a missing dependency.
  // Check the device logs for more information.
  return;
}

// Poll the future to wait for its completion either in this
// thread, or as part of your game loop by calling
// firebase::gma::InitializeLastResult();
while (future.status() == firebase::kFutureStatusPending) {
  // Initialization on-going, continue to wait.
}

// future.status() is either kFutureStatusComplete or there’s an error

if (future.status() == firebase::kFutureStatusComplete &&
     future.error() == firebase::gma::AdErrorCodeNone) {
  AdapterInitializationStatus* status = future.result();
  // Check status for any mediation adapters you wish to use.
  // ..
} else {
  // Handle initialization error.
}

Изменения AdSize в AdView

AdSize теперь содержит статические элементы распространенных размеров баннерной рекламы и поддерживает размеры рекламы AnchorAdaptive и InlineAdaptive , которые имеют динамическую высоту, основанную на заданной ширине и текущей ориентации экрана.

Статические константы AdSize добавлены в firebase::gma::AdSize
AdSize::kBanner	Размер баннерной рекламы Ассоциации мобильного маркетинга (MMA) (320x50 пикселей, не зависящих от плотности)
AdSize::kFullBanner	Полный размер баннера Interactive Advertising Bureau (IAB) (468x60 пикселей, не зависящих от плотности)
AdSize::kLargeBanner	Более высокая версия kBanner , обычно 320x100
AdSize::kLeaderboard	Размер рекламного баннера Interactive Advertising Bureau (IAB) (728x90 пикселей, не зависящих от плотности)
AdSize::kMediumRectangle	Средний размер прямоугольной рекламы Interactive Advertising Bureau (IAB) (300x250 пикселей, не зависящих от плотности)

Статические методы в firebase::gma::AdSize для помощи в создании экземпляров AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize	Создает AdSize с заданной шириной и оптимизированной Google высотой для создания баннерной рекламы в ландшафтном режиме.
GetPortraitAnchoredAdaptiveBannerAdSize	Создает AdSize с заданной шириной и оптимизированной Google высотой для создания баннерной рекламы в портретном режиме.
GetCurrentOrientationAnchoredAdaptiveBannerAdSize	Создает AdSize с заданной шириной и оптимизированной Google высотой для создания баннерной рекламы с учетом текущей ориентации.
GetInlineAdaptiveBannerAdSize	Создает AdSize , наиболее подходящий для баннерной рекламы с учетом максимальной высоты Этот AdSize позволяет серверам Google выбирать оптимальный размер объявления с высотой, меньшей или равной указанной максимальной высоте.
GetLandscapeInlineAdaptiveBannerAdSize	Создает InlineAdaptive AdSize с заданной шириной и высотой в альбомной ориентации устройства.
GetPortraitInlineAdaptiveBannerAdSize	Создает InlineAdaptive AdSize с заданной шириной и высотой портретного расположения устройства.
GetCurrentOrientationInlineAdaptiveBannerAdSize	Удобный метод для возврата InlineAdaptive AdSize с учетом текущей ориентации интерфейса и определенной ширины.

До

firebase::admob::BannerView* banner_view = new firebase::admob::BannerView();

firebase::admob::AdSize ad_size;
ad_size.ad_size_type = firebase::admob::kAdSizeStandard;
ad_size.width = 320;
ad_size.height = 50;

// ad_parent is a reference to an iOS UIView or an Android Activity.
// banner_ad_unit is your ad unit id for banner ads.
banner_view->Initialize(ad_parent, banner_ad_unit, ad_size);

После

firebase::gma::AdView* ad_view = new firebase::gma::AdView();

// ad_parent is a reference to an iOS UIView or an Android Activity.
// banner_ad_unit is your ad unit id for banner ads.
banner_view->Initialize(ad_parent, banner_ad_unit, firebase::gma::AdSize.kBanner);

AdRequest и глобальная конфигурация

Идентификаторы тестовых устройств, TagForChildDirectedTreatment и TagForUnderAgeOfConsent (ранее обрабатывавшиеся по дню рождения) были удалены из AdRequest и теперь являются частью глобального RequestConfiguration . Приложения могут вызывать firebase::gma::SetRequestConfiguration() на ранних этапах жизненного цикла приложения для настройки этих значений. Все последующие операции загрузки рекламы будут учитывать эти настройки после их настройки.

firebase::gma::AdRequest все еще существует, поскольку он предоставляет контекстную информацию для загрузки рекламы, включая ключевые слова и необязательный URL-адрес контента.

Структура AdRequest в стиле C от AdMob была заменена классом с методами, которые обеспечивают лучший пользовательский интерфейс при определении и добавлении в различные списки информации.

Вот примечательные изменения AdRequest :

• Дополнения теперь связаны с именем класса адаптера посредничества. Дополнения, отправленные в службу AdMob , должны использовать имя класса по умолчанию, как определено ниже.
• При запросе рекламы приложения могут передавать URL-адрес контента, который они обслуживают. Это позволяет таргетингу ключевых слов сопоставлять рекламу с другим отображаемым контентом.

До

firebase::admob::AdRequest request;

// Keywords to be used in targeting.
const char* keywords[] = {"GMA", "C++", "Fun"};
request.keyword_count = sizeof(keywords) / sizeof(keywords[0]);
request.keywords = keywords;

// "Extra" key value pairs.
static const firebase::admob::KeyValuePair extras[] = {
      {"extra_name", "extra_value"}};
request.extras_count = sizeof(extras) / sizeof(extras[0]);
request.extras = kRequestExtras;

// Devices that should be served test ads.
const char* test_device_ids[] ={ "123", "4567", "890" };
request.test_device_id_count =
      sizeof(test_device_ids) / sizeof(test_device_ids[0]);
request.test_device_ids = test_device_ids;

// Sample birthday to help determine the age of the user.
request.birthday_day = 10;
request.birthday_month = 11;
request.birthday_year = 1975;

// Load Ad with the AdRequest.

После

// Do once after Google Mobile Ads C++ SDK initialization.
// These settings will affect all Ad Load operations.
firebase::gma::RequestConfiguration configuration;
configuration.max_ad_content_rating =
      firebase::gma::RequestConfiguration::kMaxAdContentRatingPG;
configuration.tag_for_child_directed_treatment =
      firebase::gma::RequestConfiguration::kChildDirectedTreatmentTrue;
configuration.tag_for_under_age_of_consent =
      firebase::gma::RequestConfiguration::kUnderAgeOfConsentFalse;
configuration.test_device_ids.push_back("1234");
configuration.test_device_ids.push_back("4567");
configuration.test_device_ids.push_back("890");
firebase::gma::SetRequestConfiguration(configuration);

// Then, more information must be provided via an AdRequest when
// loading individual ads.
firebase::gma::AdRequest ad_request;

// "Extra" key value pairs.
ad_request.add_keyword("GMA");
ad_request.add_keyword("C++");
ad_request.add_keyword("Fun");

// Content URL.
ad_request.set_content_url("www.example.com");

// Mediation Adapter Extras.
#if defined(Android)
const char* ad_network_extras_class_name =
    "com/google/ads/mediation/admob/AdMobAdapter";
#else  // iOS
const char* ad_network_extras_class_name = "GADExtras";
#endif

ad_request.add_extra(ad_network_extras_class_name, "extra_name", "extra_value");

// Load Ad with the AdRequest. See next section.

AdResults

LoadAd теперь возвращает Future , содержащий объект AdResult для всех типов объявлений AdView , InterstitialAd и RewardedAd . Метод AdResult::is_successful возвращает true если запрос объявления был успешно выполнен, или false в противном случае.

В случае сбоя AdResult содержит объект AdError с информацией о проблеме на уровне обслуживания, включая код ошибки, сообщение об ошибке и строки домена.

До

firebase::Future<AdResult> future;

void load_ad() {
  // Assume an already created AdRequest object.
  future = ad_view->LoadAd(ad_request);
}

void your_game_loop() {
  if (future.status() == firebase::kFutureStatusComplete) {
    if(future.error() != firebase::admob::kAdMobErrorNone) {
      // There was either an internal SDK issue that caused the Future to
      // fail its completion, or AdMob failed to fulfill the ad request.
      // Details are unknown other than the Future’s error code returned
      // from future.error().
    } else {
      // The ad loaded successfully.
    }
  }
}

После

firebase::Future<AdResult> future;

void load_ad() {
  // Assumes a previously created AdRequest object.
  // See "AdRequest and Global Configuration" above.
  future = ad_view->LoadAd(ad_request);
}

void your_game_loop() {
  // Check the future status in your game loop:
  if (future.status() == firebase::kFutureStatusComplete) {
    if(future.error() != firebase::admob::kAdErrorCodeNone) {
      // There was an internal SDK issue that caused the Future to fail.
    } else {
      // Future completed successfully.  Check the GMA result.
      const AdResult* ad_result = future.result();
      if ( ad_result->is_successful() != true ) {
        // GMA failed to serve an ad. Gather information about the error.
        const AdError& ad_error = ad_result->ad_error();
        AdErrorCode error_code = ad_error.code();
        const std::string error_domain = ad_error.domain();
        const std::string error_message = ad_error.message();
      } else {
        // The ad loaded successfully.
      }
    }
  }
}

События AdListener в AdView

BannerView::Listener AdMob был заменен двумя отдельными классами прослушивателя в Google Mobile Ads C++ SDK:

• AdListener отслеживает жизненный цикл рекламы и события взаимодействия с пользователем.
• AdViewBoundingBoxListener вызывается при изменении размера или перемещении AdView .

Обратный вызов AdMob OnPresentationStateChanged Сопоставления Google Mobile Ads

Перечислимый тип firebase::admob::BannerView::PresentationState и метод прослушивателя OnPresentationStateChanged не включены в новый Google Mobile Ads C++ SDK.

Ниже приведены альтернативные способы обнаружения изменений состояния представления в жизненном цикле AdView :

firebase::admob::BannerView::Listener OnPresentationStateChanged	firebase::gma::AdListener аналог
kPresentationStateHidden	Когда вызывается AdListener::OnAdClosed или когда AdView::Hide() успешно завершает свою асинхронную операцию
kPresentationStateVisibleWithoutAd	Нет. Попытка вызвать AdView::Show() незагруженного AdView приведет к ошибке.
kPresentationStateVisibleWithAd	Когда вызывается AdListener::OnAdOpened или когда AdView::Show() успешно завершает свою асинхронную операцию с рекламой
kPresentationStateOpenedPartialOverlay	Запросите ограничивающий блок после AdListener::OnAdOpened() для определения размера и положения показываемой рекламы. В качестве альтернативы запросите положение AdView и AdSize и/или отслеживайте ограничивающий блок через AdViewBoundingBoxListener .
kPresentationStateCoveringUI	См. kPresentationStateOpenedPartialOverlay выше.

RewardedAd теперь класс

Устаревший Firebase AdMob C++ SDK облегчал рекламу с вознаграждением через набор функций в пространстве имен firebase::admob::rewarded_ad . Эти функции были объединены в новый класс RewardedAd , который обслуживает рекламу с API-поверхностью, похожей на InterstitialAd (см. следующий раздел).

Слушатели InterstitialAd и RewardedAd

Как промежуточные, так и вознагражденные объявления считаются полноэкранными объявлениями. Можно установить новый FullScreenContentListener для прослушивания событий жизненного цикла рекламы для этих типов объявлений, а также можно установить отдельный PaidEventListener для отслеживания того, когда служба AdMob посчитала, что произошло платное событие.

RewardedAd имеет дополнительный прослушиватель для отслеживания событий вознаграждения пользователя.

Новые методы обратного вызова полноэкранной рекламы

Методы FullScreenContentListener	Методы PaidEventListener	Методы UserEarnedRewardListener
OnAdClicked	OnPaidEvent	OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

Методы изменены/удалены/заменены

В таблице ниже перечислены конкретные методы, измененные в новом Google Mobile Ads C++ SDK. Методы с перечисленными параметрами остались, но их сигнатуры изменились.

Сорт	API-интерфейс Firebase AdMob C++ SDK	API C++ SDK для мобильных объявлений Google	Примечания
BannerView	MoveTo	AdView::SetPosition
	presentation_state	Удаленный	Обрабатывается событиями AdViewListener и будущими результатами AdView::Show и AdView::Hide .
	SetListener	AdView::SetAdListener AdView::SetBoundingBoxListener AdView::SetPaidEventListener	Новый дизайн прослушивателя повышает точность обнаружения событий жизненного цикла AdView .
	Listener::OnPresentationStateChanged	Удаленный	См. BannerView::SetListener выше.
	Listener::OnBoundingBoxChanged	AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd	Initialize(AdParent parent, const char* ad_unit_id)	Initialize(AdParent parent)	Параметр ad_unit_id теперь является частью операции LoadAd .
	LoadAd(const AdRequest& request)	LoadAd(const char* ad_unit_id, const AdRequest& request)
	presentation_state	Удаленный	Перечисление presentation_state удалено. Используйте FullScreenContentListener .
	SetListener	SetFullScreenContentListener SetPaidEventListener
	Destroy	Удаленный	Очистка ресурсов теперь является частью деструктора RewardedAd .
RewardedAd (формально RewardedVideoAd )	Initialize	Initialize(AdParent parent)	Ранее AdParent передавался в Show , но теперь является частью инициализации.
	presentation_state	Удаленный	Перечисление presentation_state удалено. Используйте FullScreenContentListener .
	SetListener	SetFullScreenContentListener SetPaidEventListener Show	Прослушиватель UserEarnedReward также определяется при показе RewardedAd . См. ниже.
	Show(AdParent parent)	Show(UserEarnedRewardListener* listener)