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

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.

Devolución de llamada de AdMob de OnPresentationStateChanged en asignaciones de anuncios de Google para dispositivos móviles

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:

Evento firebase::admob::BannerView::Listener OnPresentationStateChanged 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)