Migrer vers le nouveau SDK Google Mobile Ads C++

La version 9.1.0 du SDK C++ Firebase introduit un nouveau SDK Google Mobile Ads C++.

Le SDK Google Mobile Ads C++ est une nouvelle surface d'API qui intègre les modifications majeures apportées aux SDK C++ Firebase AdMob pour iOS et Android en 2021 et 2022, y compris la suppression des API obsolètes et un nouveau flux lorsque vous travaillez avec des types d'annonces en plein écran.

L'ancien SDK Firebase AdMob C++ (firebase::admob) a été marqué comme obsolète et ne recevra plus de mises à jour ni de corrections de bugs.

Le nouveau SDK Google Mobile Ads C++ (firebase::gma) et l'ancien SDK Firebase AdMob C++ (firebase::admob) resteront dans les archives de compilation du SDK C++ Firebase pendant la période d'abandon du SDK Firebase AdMob C++.

Suppression de l'ancienne API

Les API suivantes ont été supprimées intégralement du SDK Google Mobile Ads C++.

RewardedVideoAd

L'espace de noms RewardedVideoAd d'AdMob a été remplacé par la classe RewardedAd. RewardedAd se comporte de manière similaire à InterstitialAd, mais inclut un RewardedAdListener supplémentaire pour recevoir une notification des récompenses d'articles.

NativeExpressAds

NativeExpressAd d'AdMob avait déjà été marqué comme obsolète dans chaque SDK Firebase AdMob C++. Par conséquent, NativeExpressAd n'est pas inclus dans le nouveau SDK Google Mobile Ads C++.

Modification de l'espace de noms du SDK

Le SDK a été déplacé vers un nouvel espace de noms et dispose d'une nouvelle structure de répertoire:

Espace de noms firebase::gma

Les sources du nouveau SDK Google Mobile Ads C++ se trouvent dans l'espace de noms firebase::gma. L'ancien espace de noms firebase::admob a été abandonné avec le SDK Firebase AdMob C++.

Structure des répertoires

Les fichiers d'en-tête ont été déplacés vers un nouveau répertoire dans l'archive de compilation:

SDK Firebase AdMob C++ obsolète	Nouveau SDK Google Mobile Ads C++
include/firebase/admob	include/firebase/gma

Bibliothèque

Le SDK Firebase AdMob C++ est fourni en tant que bibliothèque statique dans l'archive de compilation du SDK Firebase C++:

Migrations de classe, d'énumération et de structure

Le tableau ci-dessous liste les classes, énumérations et structures spécifiques qui ont été modifiées ou supprimées. Voici un récapitulatif:

• BannerView a été renommé AdView.
• "NativeAdExpressView" a bien été supprimé.
• L'espace de noms RewardedVideo est remplacé par une classe RewardedAd.
• L'énumération et les écouteurs PresentationState sont supprimés et remplacés par des écouteurs AdListener et FullScreenContent.

• Les paramètres suivants sont supprimés en tant que paramètres de configuration par annonce dans AdRequests:

  • la configuration des ID d'appareils de test ;
  • le ciblage des annonces en fonction de l'âge ;

  À la place, vous pouvez désormais configurer ces paramètres dans RequestConfiguration, un paramètre global qui affectera toutes les charges d'annonces ultérieures.

Abandon de firebase::admob namespace	Nouveau firebase::gma namespace
AdSizeType (enum)	AdSize::Type (enum)
BannerView	AdView
BannerView::Listener	AdListener AdViewBoundingBoxListener PaidEventListener
BannerView::Position	AdView::Position
BannerView::PresentationState	Supprimé
ChildDirectedTreatmentState	RequestConfiguration::TagForChildDirectedTreatment
Gender (enum)	Supprimé
InterstitialAd::Listener	FullScreenContentListener PaidEventListener
KeyValuePair	Supprimé
NativeExpressAdView	Supprimé
PollableRewardListener	Supprimé
RewardItem	AdReward
RewardedVideoAd (espace de noms)	RewardedAd (classe)
RewardedVideoAd::Listener	FullScreenContentListener PaidEventListener UserEarnedRewardListener
AdMobError (enum)	AdErrorCode (enum)
RewardItem	AdReward

Initialisation du SDK

Chaque fonction d'initialisation du SDK Google Mobile Ads C++ renvoie immédiatement deux indicateurs d'état:

• Un paramètre out facultatif indique si une erreur de dépendance s'est produite avant le début du processus d'initialisation.

• Le paramètre de retour est une référence à un firebase::Future. Future contient les résultats de l'initialisation asynchrone des adaptateurs de médiation sur l'appareil.

Bien que le SDK Google Mobile Ads C++ puisse être appelé pour charger les annonces diffusées par AdMob dès que la fonction d'initialisation est renvoyée, les autres réseaux publicitaires ne diffuseront pas d'annonces tant que leur adaptateur de médiation correspondant n'a pas été entièrement initialisé. Ce processus se produit de manière asynchrone. Par conséquent, si vous utilisez la médiation publicitaire dans votre application, nous vous recommandons d'attendre que la Future soit résolue avant d'essayer de charger des annonces.

Avant

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

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

Modifications apportées à AdSize dans AdView

AdSize contient désormais des membres statiques des tailles d'annonces bannières courantes et est compatible avec les tailles d'annonces AnchorAdaptive et InlineAdaptive, qui ont une hauteur dynamique en fonction de la largeur donnée et de l'orientation actuelle de l'écran.

Constantes AdSize statiques ajoutées à firebase::gma::AdSize
AdSize::kBanner	Taille de bannière de la Mobile Marketing Association (MMA) (320 x 50 pixels indépendants de la densité)
AdSize::kFullBanner	Taille de bannière complète de l'Interactive Advertising Bureau (IAB) (468 x 60 pixels indépendants de la densité)
AdSize::kLargeBanner	Version plus haute de kBanner, généralement 320 x 100
AdSize::kLeaderboard	Taille d'annonce leaderboard de l'Interactive Advertising Bureau (IAB) (728 x 90 pixels indépendants de la densité)
AdSize::kMediumRectangle	Taille d'annonce de rectangle moyen de l'Interactive Advertising Bureau (IAB) (300 x 250 pixels indépendants de la densité)

Méthodes statiques dans firebase::gma::AdSize pour aider à créer des instances de AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize	Crée un AdSize avec la largeur donnée et une hauteur optimisée par Google pour créer une bannière publicitaire en mode paysage.
GetPortraitAnchoredAdaptiveBannerAdSize	Crée un AdSize avec la largeur donnée et une hauteur optimisée par Google pour créer une bannière publicitaire en mode portrait.
GetCurrentOrientationAnchoredAdaptiveBannerAdSize	Crée un AdSize avec la largeur donnée et une hauteur optimisée par Google pour créer une bannière publicitaire en fonction de l'orientation actuelle.
GetInlineAdaptiveBannerAdSize	Crée un AdSize le plus adapté aux bannières publicitaires en fonction d'une hauteur maximale. Cette AdSize permet aux serveurs Google de choisir une taille d'annonce optimale dont la hauteur est inférieure ou égale à une hauteur maximale spécifiée.
GetLandscapeInlineAdaptiveBannerAdSize	Crée un AdSize InlineAdaptive avec la largeur donnée et la hauteur en mode paysage de l'appareil.
GetPortraitInlineAdaptiveBannerAdSize	Crée un AdSize InlineAdaptive avec la largeur donnée et la hauteur portrait de l'appareil.
GetCurrentOrientationInlineAdaptiveBannerAdSize	Méthode pratique permettant de renvoyer InlineAdaptive AdSize en fonction de l'orientation actuelle de l'interface et d'une largeur spécifique.

Avant

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

Aprè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 et configuration globale

Les ID d'appareil de test, TagForChildDirectedTreatment et TagForUnderAgeOfConsent (gérés auparavant par l'anniversaire) ont été supprimés de AdRequest et font désormais partie d'un RequestConfiguration global. Les applications peuvent appeler firebase::gma::SetRequestConfiguration() au début du cycle de vie de l'application pour configurer ces valeurs. Une fois ces paramètres configurés, toutes les opérations de chargement d'annonces ultérieures les respecteront.

firebase::gma::AdRequest existe toujours, car il fournit des informations contextuelles pour le chargement d'annonces, y compris des mots clés et une URL de contenu facultative.

La struct de style C AdRequest d'AdMob a été remplacée par une classe avec des méthodes qui offrent une meilleure expérience utilisateur lors de la définition et de l'ajout aux différentes listes d'informations.

Voici les modifications importantes apportées à AdRequest:

• Les extras sont désormais associés à un nom de classe d'adaptateur de médiation. Les éléments supplémentaires envoyés au service AdMob doivent utiliser le nom de classe par défaut, comme défini ci-dessous.
• Lorsqu'elles demandent une annonce, les applications peuvent transmettre l'URL du contenu qu'elles diffusent. Cela permet au ciblage par mots clés de faire correspondre l'annonce à d'autres contenus affichés.

Avant

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.

Aprè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

LoadAd renvoie désormais un Future contenant un objet AdResult pour tous les types d'annonces AdView, InterstitialAd et RewardedAd. La méthode AdResult::is_successful renvoie true si la requête d'annonce a abouti, ou false si ce n'est pas le cas.

En cas d'échec, AdResult contient un objet AdError contenant des informations de niveau de service sur le problème, y compris le code d'erreur, le message d'erreur et les chaînes de domaine.

Avant

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

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

Événements AdListener dans AdView

La classe BannerView::Listener d'AdMob a été remplacée par deux classes d'écouteurs distinctes dans le SDK Google Mobile Ads C++:

• AdListener suit le cycle de vie des annonces et les événements d'interaction utilisateur.
• AdViewBoundingBoxListener est appelé lorsque la AdView est redimensionnée ou déplacée.

AdMob : mappages des rappels OnPresentationStateChanged Google Mobile Ads

Le type énuméré firebase::admob::BannerView::PresentationState et la méthode d'écouteur OnPresentationStateChanged ne sont pas inclus dans le nouveau SDK Google Mobile Ads C++.

Voici d'autres façons de détecter les changements d'état de la présentation dans le cycle de vie d'un AdView:

firebase::admob::BannerView::Listener OnPresentationStateChanged événement	firebase::gma::AdListener homologue
kPresentationStateHidden	Lorsque AdListener::OnAdClosed est appelé ou lorsque AdView::Hide() termine son opération asynchrone
kPresentationStateVisibleWithoutAd	Aucune. Toute tentative d'appel de AdView::Show() d'un AdView non chargé entraînera une erreur.
kPresentationStateVisibleWithAd	Lorsque AdListener::OnAdOpened est appelé ou lorsque AdView::Show() termine son opération asynchrone avec une annonce
kPresentationStateOpenedPartialOverlay	Interrogez le cadre de délimitation après l'appel de AdListener::OnAdOpened() pour déterminer la taille et la position de l'annonce affichée. Vous pouvez également interroger la position de AdView et de AdSize, et/ou surveiller la zone de délimitation via AdViewBoundingBoxListener.
kPresentationStateCoveringUI	Voir kPresentationStateOpenedPartialOverlay ci-dessus

RewardedAd est désormais une classe

Le SDK C++ Firebase AdMob obsolète facilitait les annonces avec récompense via une collection de fonctions dans l'espace de noms firebase::admob::rewarded_ad. Ces fonctions ont été fusionnées dans une nouvelle classe RewardedAd qui diffuse des annonces avec une surface d'API semblable à celle de InterstitialAd (voir la section suivante).

Écouteurs InterstitialAd et RewardedAd

Les annonces interstitielles et les annonces avec récompense sont considérées comme des annonces plein écran. Vous pouvez installer un nouveau FullScreenContentListener pour écouter les événements de cycle de vie des annonces pour ces types d'annonces, et un PaidEventListener distinct peut être installé pour suivre quand le service AdMob a déterminé qu'un événement payant s'était produit.

RewardedAd dispose d'un écouteur supplémentaire pour surveiller les événements de récompenses gagnées par l'utilisateur.

Nouvelles méthodes de rappel pour les annonces plein écran

FullScreenContentListener méthodes	PaidEventListener méthodes	UserEarnedRewardListener méthodes
OnAdClicked	OnPaidEvent	OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

Méthodes modifiées/supprimées/remplacées

Le tableau ci-dessous liste les méthodes spécifiques modifiées dans le nouveau SDK Google Mobile Ads C++. Les méthodes avec paramètres listés restent, mais leurs signatures ont changé.

Classe	API du SDK Firebase AdMob C++	API du SDK Google Mobile Ads C++	Remarques
BannerView	MoveTo	AdView::SetPosition
	presentation_state	Supprimé	Géré par les événements AdViewListener et les résultats futurs AdView::Show et AdView::Hide.
	SetListener	AdView::SetAdListener AdView::SetBoundingBoxListener AdView::SetPaidEventListener	La nouvelle conception de l'écouteur améliore la fidélité de la détection des événements de cycle de vie AdView.
	Listener::OnPresentationStateChanged	Supprimé	Voir BannerView::SetListener ci-dessus.
	Listener::OnBoundingBoxChanged	AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd	Initialize(AdParent parent, const char* ad_unit_id)	Initialize(AdParent parent)	Le paramètre ad_unit_id fait désormais partie de l'opération LoadAd.
	LoadAd(const AdRequest& request)	LoadAd(const char* ad_unit_id, const AdRequest& request)
	presentation_state	Supprimé	L'énumération presentation_state a été supprimée. Utilisez FullScreenContentListener.
	SetListener	SetFullScreenContentListener SetPaidEventListener
	Destroy	Supprimé	Le nettoyage des ressources fait désormais partie du destructeur RewardedAd.
RewardedAd (formellement RewardedVideoAd)	Initialize	Initialize(AdParent parent)	AdParent était auparavant transmis à Show, mais fait désormais partie de l'initialisation.
	presentation_state	Supprimé	L'énumération presentation_state a été supprimée. Utilisez FullScreenContentListener.
	SetListener	SetFullScreenContentListener SetPaidEventListener Show	Un écouteur UserEarnedReward est également défini lors de l'affichage d'un RewardedAd. Voir ci-dessous.
	Show(AdParent parent)	Show(UserEarnedRewardListener* listener)