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

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

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

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

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

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

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

RewardedVideoAd

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

NativeExpressAds

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

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

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

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

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

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

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

Библиотека

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

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

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

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

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

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

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

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

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

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

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

Хотя SDK Google Mobile Ads C++ можно вызвать для загрузки объявлений, показываемых 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 , которые имеют динамическую высоту в зависимости от заданной ширины и текущей ориентации экрана.

До

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 в AdMob в стиле 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 был заменен двумя отдельными классами-прослушивателями в SDK Google Mobile Ads C++:

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

Обратный вызов AdMob OnPresentationStateChanged Сопоставления мобильных объявлений Google

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

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

RewardedAd теперь является классом

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

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

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

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

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

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

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