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


FirebaseC++ SDK версии 9.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

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

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 Новый Google Mobile Ads C++ SDK
include/firebase/admob include/firebase/gma

Библиотека

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

iOS

Прекращение поддержки Firebase AdMob C++ SDK Новый Google Mobile Ads C++ SDK
firebase_admob.xcframework firebase_gma.xcframework

Android

Прекращение поддержки Firebase AdMob C++ SDK Новый Google Mobile Ads C++ SDK
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 сразу возвращает два индикатора статуса:

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

  • Возвращаемый параметр – это ссылка на 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): 320 x 50 пикселей, не зависящих от плотности экрана.

AdSize::kFullBanner
Полноразмерный баннер по стандартам Бюро интерактивной рекламы (IAB) (468 x 60 пикселей, не зависящих от плотности экрана).
AdSize::kLargeBanner Более высокий вариант kBanner, обычно 320 x 100.

AdSize::kLeaderboard
Полноразмерный баннер, соответствующий стандартам Бюро интерактивной рекламы (IAB) (728 x 90 пикселей, не зависящих от плотности экрана).
AdSize::kMediumRectangle Средний прямоугольник по стандартам Бюро интерактивной рекламы (IAB) (300 x 250 пикселей, не зависящих от плотности экрана).
Статические методы в 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 (ранее обрабатывались с помощью birthday) были удалены из AdRequest и теперь являются частью глобального RequestConfiguration. Приложения могут вызывать firebase::gma::SetRequestConfiguration() на ранних этапах своего жизненного цикла, чтобы задавать эти значения. После этого все последующие операции по загрузке объявлений будут выполняться с учетом заданных настроек.

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

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

Вот основные изменения в 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 изменяется.

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

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

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

firebase::admob::BannerView::Listener OnPresentationStateChanged событие firebase::gma::AdListener counterpart
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, а чтобы отслеживать, когда сервис AdMob регистрирует платное событие, – отдельный PaidEventListener.

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

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

FullScreenContentListener способов PaidEventListener способов UserEarnedRewardListener способов
OnAdClicked OnPaidEvent OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

Измененные, удаленные или замененные методы

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

Класс Firebase AdMob C++ SDK API Google Mobile Ads C++ SDK API Примечания
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 		При показе RewardedAd также определяется прослушиватель UserEarnedReward. Инструкции приводятся ниже.
Show(AdParent parent) Show(UserEarnedRewardListener* listener)