Migra al nuevo SDK de C++ de anuncios de Google para dispositivos móviles

El lanzamiento de la versión 9.1.0 del SDK de Firebase C++ incluye un nuevo SDK de C++ de anuncios de Google para dispositivos móviles.

El SDK de C++ de anuncios de Google para dispositivos móviles es una nueva plataforma de API que incorpora los principales cambios rotundos que se realizaron en los SDK de Firebase AdMob C++ para iOS y Android en 2021 y 2022, incluidos la eliminación de las APIs obsoletas y un nuevo flujo cuando se trabaja con tipos de anuncios de pantalla completa.

El SDK de Firebase AdMob C++ antiguo (firebase::admob) está obsoleto y ya no recibirá actualizaciones ni correcciones de errores.

Tanto el nuevo SDK de C++ de anuncios de Google para dispositivos móviles (firebase::gma) como el antiguo SDK de Firebase AdMob C++ (firebase::admob) seguirán siendo parte de los archivos de compilación del SDK de Firebase C++ durante la ventana de baja del SDK de Firebase AdMob C++.

Eliminación de la API heredada

Se quitaron por completo las siguientes API del SDK de C++ de anuncios de Google para dispositivos móviles.

`RewardedVideoAd`

Se reemplazó el espacio de nombres RewardedVideoAd de AdMob por una clase RewardedAd. RewardedAd se comporta de manera similar a InterstitialAd, pero incluye un objeto RewardedAdListener adicional para recibir notificaciones de recompensas de elementos.

`NativeExpressAds`

NativeExpressAd de AdMob ya se había marcado como obsoleto en cada SDK de Firebase AdMob C++. Por lo tanto, no se incluye NativeExpressAd en el nuevo SDK de C++ de anuncios de Google para dispositivos móviles.

Cambio en el espacio de nombres del SDK

El SDK se trasladó a un nuevo espacio de nombres y tiene una nueva estructura de directorio:

Espacio de nombres `firebase::gma`

Las fuentes del nuevo SDK de C++ de anuncios de Google para dispositivos móviles se encuentran en el espacio de nombres firebase::gma. El espacio de nombres firebase::admob anterior dejó de estar disponible junto con el SDK de Firebase AdMob C++.

Estructura del directorio

Los archivos de encabezado se movieron a un directorio nuevo dentro del archivo de compilación:

SDK de Firebase AdMob C++ obsoleto	Nuevo SDK de C++ de anuncios de Google para dispositivos móviles
`include/firebase/admob`	`include/firebase/gma`

Biblioteca

El SDK de Firebase AdMob C++ se proporcionará como una biblioteca estática dentro del archivo de compilación del SDK de Firebase C++:

iOS

SDK de Firebase AdMob C++ obsoleto	Nuevo SDK de C++ de anuncios de Google para dispositivos móviles
`firebase_admob.xcframework`	`firebase_gma.xcframework`

Android

SDK de Firebase AdMob C++ obsoleto	Nuevo SDK de C++ de anuncios de Google para dispositivos móviles
`libfirebase_admob.a`	`libfirebase_gma.a`

Migraciones de clases, enums y structs

En la siguiente tabla, se enumeran las clases, enums y structs específicos que se cambiaron o quitaron. Aquí encontrarás un resumen:

Se cambió el nombre de BannerView por AdView.
Se quitó NativeAdExpressView.
Se reemplazó el espacio de nombres RewardedVideo por una clase RewardedAd.
Se quitaron y reemplazaron la enumeración y los objetos de escucha PresentationState por los objetos de escucha AdListener y FullScreenContent.
Se quitaron los siguientes parámetros como parámetros de configuración por anuncio en AdRequests:
- el parámetro de configuración de los ID de dispositivos de prueba
- la segmentación de los anuncios según la edad
En su lugar, estos parámetros ahora se pueden configurar en RequestConfiguration, un parámetro de configuración global que afectará a todas las cargas de anuncios posteriores.

`firebase::admob namespace` obsoleto	Nuevo `firebase::gma namespace`
`AdSizeType` (enum)	`AdSize::Type` (enum)
`BannerView`	`AdView`
`BannerView::Listener`	`AdListener` `AdViewBoundingBoxListener` `PaidEventListener`
`BannerView::Position`	`AdView::Position`
`BannerView::PresentationState`	Se quitó
`ChildDirectedTreatmentState`	`RequestConfiguration::TagForChildDirectedTreatment`
`Gender` (enum)	Se quitó
`InterstitialAd::Listener`	`FullScreenContentListener` `PaidEventListener`
`KeyValuePair`	Se quitó
`NativeExpressAdView`	Se quitó
`PollableRewardListener`	Se quitó
`RewardItem`	`AdReward`
`RewardedVideoAd` (espacio de nombres)	`RewardedAd` (clase)
`RewardedVideoAd::Listener`	`FullScreenContentListener` `PaidEventListener` `UserEarnedRewardListener`
`AdMobError` (enum)	`AdErrorCode` (enum)
`RewardItem`	`AdReward`

Inicialización del SDK

Cada función de inicialización del SDK de C++ de anuncios de Google para dispositivos móviles muestra inmediatamente dos indicadores de estado:

Un parámetro opcional de salida transmite si se produjo un error de dependencia antes de que comience el proceso de inicialización.
El parámetro que se muestra es una referencia a firebase::Future. Future contiene los resultados de la inicialización asíncrona de los adaptadores de mediación en el dispositivo.

Si bien se puede invocar el SDK de C++ de anuncios de Google para dispositivos móviles a fin de cargar anuncios publicados por AdMob apenas se muestre la función de inicialización, otras redes de publicidad no publicarán anuncios hasta que se haya inicializado por completo el adaptador de mediación correspondiente. Este proceso se realiza de forma asíncrona. Por lo tanto, si usas la mediación de anuncios en tu aplicación, te recomendamos que esperes a que se resuelva Future antes de intentar cargar cualquier anuncio.

Antes

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;
}

Después

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.
}

Cambios en `AdSize` dentro de `AdView`

Ahora AdSize contiene miembros estáticos de tamaños comunes de anuncios en forma de banner y admite tamaños de anuncios AnchorAdaptive y InlineAdaptive, que tienen una altura dinámica en función del ancho determinado y la orientación actual de la pantalla.

Se agregaron constantes `AdSize` estáticas a `firebase::gma::AdSize`
`AdSize::kBanner`	Tamaño del anuncio en forma de banner de la Asociación de marketing para dispositivos móviles (MMA) (320 × 50 píxeles independientes de la densidad)
`AdSize::kFullBanner`	Tamaño de anuncio en forma de banner completo de la Interactive Advertising Bureau (IAB) (468 × 60 píxeles independientes de la densidad)
`AdSize::kLargeBanner`	Versión más estándar de `kBanner`, normalmente de 320 × 100
`AdSize::kLeaderboard`	Tamaño de anuncio de la tabla de clasificación de la Interactive Advertising Bureau (IAB) (728 × 90 píxeles independientes de la densidad)
`AdSize::kMediumRectangle`	Tamaño publicitario de rectángulo mediano de la Interactive Advertising Bureau (IAB) (300 × 250 píxeles independientes de la densidad)

Métodos estáticos en `firebase::gma::AdSize` para ayudar a construir instancias de `AdSize`
`GetLandscapeAnchoredAdaptiveBannerAdSize`	Se crea un elemento `AdSize` con el ancho especificado y una altura optimizada por Google para crear un anuncio en forma de banner en modo horizontal.
`GetPortraitAnchoredAdaptiveBannerAdSize`	Se crea un elemento `AdSize` con el ancho especificado y una altura optimizada por Google para crear un anuncio en forma de banner en modo vertical.
`GetCurrentOrientationAnchoredAdaptiveBannerAdSize`	Se crea una `AdSize` con el ancho determinado y una altura optimizada por Google para crear un anuncio en forma de banner con la orientación actual.
`GetInlineAdaptiveBannerAdSize`	Se crea un objeto `AdSize` más adecuado para anuncios en forma de banner a partir de una altura máxima. Este `AdSize` les permite a los servidores de Google elegir un tamaño de anuncio óptimo con una altura inferior o igual a una altura máxima especificada.
`GetLandscapeInlineAdaptiveBannerAdSize`	Se crea un `InlineAdaptive` `AdSize` con el ancho dado y la altura horizontal del dispositivo.
`GetPortraitInlineAdaptiveBannerAdSize`	Se crea un `InlineAdaptive` `AdSize` con el ancho dado y la altura vertical del dispositivo.
`GetCurrentOrientationInlineAdaptiveBannerAdSize`	Un método útil para mostrar `InlineAdaptive` `AdSize` según la orientación actual de la interfaz, teniendo en cuenta un ancho específico.

Antes

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);

Después

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` y la configuración global

Se quitaron de AdRequest los ID de dispositivo de prueba, TagForChildDirectedTreatment y TagForUnderAgeOfConsent (antes controlados por fecha de nacimiento), y ahora son parte de una RequestConfiguration global. Es posible que ciertas aplicaciones invoquen firebase::gma::SetRequestConfiguration() al comienzo de su ciclo de vida para configurar estos valores. Todas las operaciones posteriores de carga de anuncios respetarán esta configuración una vez que se establezca.

Aún existe firebase::gma::AdRequest, ya que proporciona información contextual para cargar anuncios, incluidas las palabras clave y URLs de contenido opcional.

Se reemplazó el struct de estilo C AdRequest de AdMob por una clase con métodos que proporcionan una mejor experiencia del usuario cuando se definen y anexan las diversas listas de información.

Estos son algunos cambios notables en AdRequest:

Ahora las opciones adicionales se asocian con un nombre de clase de adaptador de mediación. Las opciones adicionales enviadas al servicio de AdMob deben usar el nombre de clase predeterminado, como se define a continuación.
Cuando las apps solicitan un anuncio, pueden pasar una URL del contenido que publican. Esto permite usar la segmentación por palabras clave para que el anuncio coincida con otro contenido que se muestra.

Antes

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.

Después

// 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`

Ahora LoadAd muestra un Future que contiene un objeto AdResult para todos los tipos de anuncios AdView, InterstitialAd y RewardedAd. El método AdResult::is_successful muestra true si la solicitud de anuncio se completó correctamente; de lo contrario, muestra false.

En caso de error, AdResult contiene un objeto AdError con información a nivel de servicio sobre el problema, incluidos el código de error, el mensaje de error y las strings del dominio.

Antes

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.
    }
  }
}

Después

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.
      }
    }
  }
}

Eventos de `AdListener` en `AdView`

Se reemplazó la clase BannerView::Listener de AdMob por dos clases de objeto de escucha distintas en el SDK de C++ de anuncios de Google para dispositivos móviles:

AdListener hace un seguimiento del ciclo de vida de los anuncios y de los eventos de interacción del usuario.
AdViewBoundingBoxListener se invoca cuando se cambia el tamaño o se mueve el AdView.

Asignaciones de Google Mobile Ads de devolución de llamada de `OnPresentationStateChanged` de AdMob

El tipo enumerado firebase::admob::BannerView::PresentationState y el método de objeto de escucha OnPresentationStateChanged no se incluyen en el nuevo SDK de C++ de anuncios de Google para dispositivos móviles.

Las siguientes son formas alternativas de detectar cambios en el estado de la presentación en el ciclo de vida de AdView:

`firebase::admob::BannerView::Listener OnPresentationStateChanged` evento	Contraparte `firebase::gma::AdListener`
`kPresentationStateHidden`	Cuando se invoca `AdListener::OnAdClosed` o cuando `AdView::Hide()` completa su operación asíncrona correctamente
`kPresentationStateVisibleWithoutAd`	Ninguno Si se intenta invocar a `AdView::Show()` una `AdView` no cargada, se generará un error.
`kPresentationStateVisibleWithAd`	Cuando se invoca `AdListener::OnAdOpened` o cuando `AdView::Show()` completa su operación asíncrona correctamente con un anuncio
`kPresentationStateOpenedPartialOverlay`	Consulta el cuadro de límite después de invocar `AdListener::OnAdOpened()` para determinar el tamaño y la posición del anuncio que se muestra. Como alternativa, consulta la posición de `AdView` y `AdSize`, o supervisa el cuadro de límite a través de `AdViewBoundingBoxListener`.
`kPresentationStateCoveringUI`	Consulta `kPresentationStateOpenedPartialOverlay` más arriba.

Ahora `RewardedAd` es una clase

El SDK de Firebase AdMob C++ obsoleto facilitaba la publicación de anuncios recompensados mediante una colección de funciones en el espacio de nombres firebase::admob::rewarded_ad. Estas funciones se combinaron en una nueva clase RewardedAd que publica anuncios con una superficie de API similar a InterstitialAd (consulta la siguiente sección).

Objetos de escucha `InterstitialAd` y `RewardedAd`

Los anuncios intersticiales y los recompensados se consideran anuncios de pantalla completa. Se puede instalar un nuevo FullScreenContentListener para escuchar los eventos del ciclo de vida de los anuncios para estos tipos de anuncios, y se puede instalar un PaidEventListener independiente para realizar un seguimiento cuando el servicio de AdMob considere que se produjo un evento pagado.

RewardedAd tiene un objeto de escucha adicional para supervisar los eventos de recompensas obtenidos por el usuario.

Nuevos métodos de devolución de llamada de anuncios de pantalla completa

Métodos `FullScreenContentListener`	Métodos `PaidEventListener`	Métodos `UserEarnedRewardListener`
`OnAdClicked`	`OnPaidEvent`	`OnUserEarnedReward`
`OnAdDismissedFullScreenContent`
`OnAdFailedToShowFullScreenContent`
`OnAdImpression`
`OnAdShowedFullScreenContent`

Se cambiaron, quitaron o reemplazaron métodos

En la siguiente tabla, se enumeran los métodos específicos que se modificaron en el nuevo SDK de C++ de anuncios de Google para dispositivos móviles. Los métodos con parámetros enumerados permanecen, pero cambiaron sus firmas.

Clase	API del SDK de Firebase AdMob C++	API del SDK de C++ de anuncios de Google para dispositivos móviles	Notas
`BannerView`	`MoveTo`	`AdView::SetPosition`
	`presentation_state`	Se quitó	Controlado por eventos `AdViewListener` y resultados futuros `AdView::Show` y `AdView::Hide`.
	`SetListener`	`AdView::SetAdListener` `AdView::SetBoundingBoxListener` `AdView::SetPaidEventListener`	El nuevo diseño de objeto de escucha aumenta la fidelidad de la detección de eventos de ciclo de vida de `AdView`.
	`Listener::OnPresentationStateChanged`	Se quitó	Consulta `BannerView::SetListener`, más arriba.
	`Listener::OnBoundingBoxChanged`	`AdViewBoundingBoxListener::OnBoundingBoxChanged`
InterstitialAd	`Initialize(AdParent parent, const char* ad_unit_id)`	`Initialize(AdParent parent)`	Ahora el parámetro `ad_unit_id` forma parte de la operación `LoadAd`.
	`LoadAd(const AdRequest& request)`	`LoadAd(const char* ad_unit_id, const AdRequest& request)`
	`presentation_state`	Se quitó	Se quitó la enumeración `presentation_state`. Usa `FullScreenContentListener`.
	`SetListener`	`SetFullScreenContentListener` `SetPaidEventListener`
	`Destroy`	Se quitó	La limpieza de recursos ahora forma parte del destructor `RewardedAd`.
`RewardedAd` (formalmente `RewardedVideoAd`)	`Initialize`	`Initialize(AdParent parent)`	Antes se pasaba `AdParent` a `Show`, pero ahora forma parte de la inicialización.
	`presentation_state`	Se quitó	Se quitó la enumeración `presentation_state`. Usa `FullScreenContentListener`.
	`SetListener`	`SetFullScreenContentListener` `SetPaidEventListener` `Show`	También se define un objeto de escucha `UserEarnedReward` cuando se muestra un `RewardedAd`. Consulta a continuación.
	`Show(AdParent parent)`	`Show(UserEarnedRewardListener* listener)`

Migra al nuevo SDK de C++ de anuncios de Google para dispositivos móviles

Eliminación de la API heredada

RewardedVideoAd

NativeExpressAds

Cambio en el espacio de nombres del SDK

Espacio de nombres firebase::gma

Estructura del directorio

Biblioteca

iOS

Android

Migraciones de clases, enums y structs

Inicialización del SDK

Antes

Después

Cambios en AdSize dentro de AdView

Antes

Después

AdRequest y la configuración global

Antes

Después

AdResults

Antes

Después

Eventos de AdListener en AdView

Asignaciones de Google Mobile Ads de devolución de llamada de OnPresentationStateChanged de AdMob

Ahora RewardedAd es una clase

Objetos de escucha InterstitialAd y RewardedAd

Nuevos métodos de devolución de llamada de anuncios de pantalla completa

Se cambiaron, quitaron o reemplazaron métodos

`RewardedVideoAd`

`NativeExpressAds`

Espacio de nombres `firebase::gma`

Cambios en `AdSize` dentro de `AdView`

`AdRequest` y la configuración global

`AdResults`

Eventos de `AdListener` en `AdView`

Asignaciones de Google Mobile Ads de devolución de llamada de `OnPresentationStateChanged` de AdMob

Ahora `RewardedAd` es una clase

Objetos de escucha `InterstitialAd` y `RewardedAd`