Migrer vers le nouveau SDK Google Mobile Ads C++

OBSOLÈTE : Le SDK Google Mobile Ads C++ est obsolète depuis le 17 juin 2024 et ne doit pas être adopté dans les projets qui ne l'utilisent pas déjà. Il entrera en fin de maintenance le 17 juin 2025. Notez que les versions du SDK publiées avant la date d'arrêt continueront de fonctionner, mais qu'aucun autre correctif ni aucune autre modification ne seront publiés après cette date.

Au lieu du SDK Google Mobile Ads C++, envisagez d'utiliser les SDK iOS et Android de AdMob. Pour obtenir de l'aide, contactez le forum technique du SDK Google Mobile Ads.

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

Le SDK Google Mobile Ads C++ est une nouvelle surface d'API qui intègre les principaux changements incompatibles apportés aux SDK Firebase AdMob C++ pour iOS et Android en 2021 et 2022, y compris la suppression des API obsolètes et un nouveau flux pour les types d'annonces 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 tous deux dans les archives de compilation du SDK Firebase C++ pendant la période d'arrêt du SDK Firebase AdMob C++.

Suppression de l'ancienne API

Les API suivantes ont été entièrement supprimées 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 la même manière que InterstitialAd, mais inclut un RewardedAdListener supplémentaire pour recevoir une notification des récompenses d'articles.

NativeExpressAds

Le 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 C++ Google Mobile Ads.

Modification de l'espace de noms du SDK

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

Espace de noms firebase::gma

Les sources du nouveau SDK C++ Google Mobile Ads se trouvent dans l'espace de noms firebase::gma. L'ancien espace de noms firebase::admob a été abandonné en même temps que 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++ sera fourni sous forme de bibliothèque statique dans l'archive de compilation du SDK Firebase C++ :

iOS

SDK Firebase AdMob C++ obsolète	Nouveau SDK Google Mobile Ads C++
firebase_admob.xcframework	firebase_gma.xcframework

Android

SDK Firebase AdMob C++ obsolète	Nouveau SDK Google Mobile Ads C++
libfirebase_admob.a	libfirebase_gma.a

Migrations de classes, d'énumérations et de structs

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 les é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 publicités en fonction de l'âge ;

  À la place, ces paramètres peuvent désormais être configurés dans RequestConfiguration, qui est un paramètre global qui affectera tous les chargements d'annonces ultérieurs.

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 (cours)
RewardedVideoAd::Listener	FullScreenContentListener PaidEventListener UserEarnedRewardListener
AdMobError (enum)	AdErrorCode (enum)
RewardItem	AdReward

Initialisation du SDK

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

• Un paramètre de sortie 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 des annonces diffusées par AdMob dès que la fonction d'initialisation est renvoyée, d'autres réseaux publicitaires ne diffuseront pas d'annonces tant que leur adaptateur de médiation correspondant n'aura pas été entièrement initialisé. Ce processus s'effectue de manière asynchrone. Par conséquent, si vous utilisez la médiation d'annonces dans votre application, nous vous recommandons d'attendre que le problème Future soit résolu avant de tenter 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 au cours de AdView

AdSize contient désormais des membres statiques de tailles de bannières publicitaires courantes et est compatible avec les tailles d'annonces AnchorAdaptive et InlineAdaptive, dont la hauteur est 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 la bannière publicitaire 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 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 à construire 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 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 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 en fonction de l'orientation actuelle.
GetInlineAdaptiveBannerAdSize	Crée un AdSize le plus adapté aux bannières publicitaires, en fonction d'une hauteur maximale. Ce 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 InlineAdaptive AdSize avec la largeur donnée et la hauteur du 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 pour renvoyer InlineAdaptive AdSize en fonction de l'orientation actuelle de l'interface, avec 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'appareils de test, TagForChildDirectedTreatment et TagForUnderAgeOfConsent (auparavant gérés 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() tôt dans le cycle de vie de l'application pour configurer ces valeurs. Toutes les opérations de chargement d'annonces ultérieures respecteront ces paramètres une fois qu'ils seront configurés.

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

La structure 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 principales modifications apportées à AdRequest :

• Les extras sont désormais associés à un nom de classe d'adaptateur de médiation. Les extras envoyés au service AdMob doivent utiliser le nom de classe par défaut 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 demande d'annonce a été traitée avec succès, ou false dans le cas contraire.

En cas d'échec, AdResult contient un objet AdError avec des informations au niveau du 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.
      }
    }
  }
}

AdListener événements 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 AdView est redimensionné ou déplacé.

Mappages des OnPresentationStateChanged de rappel AdMob 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 C++ Google Mobile Ads.

Voici d'autres façons de détecter les changements d'état de 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 avec succès
kPresentationStateVisibleWithoutAd	Aucune. Toute tentative d'appel de AdView::Show() sur un AdView non chargé entraînera une erreur.
kPresentationStateVisibleWithAd	Lorsque AdListener::OnAdOpened est appelé ou lorsque AdView::Show() termine son opération asynchrone avec succès avec une annonce
kPresentationStateOpenedPartialOverlay	Interrogez le cadre de sélection après l'invocation 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 AdSize et/ou surveiller le cadre de sélection via AdViewBoundingBoxListener.
kPresentationStateCoveringUI	Voir kPresentationStateOpenedPartialOverlay ci-dessus

RewardedAd est désormais un cours

L'ancien SDK Firebase AdMob C++ facilitait les annonces avec récompense via une collection de fonctions dans l'espace de noms firebase::admob::rewarded_ad. Ces fonctions ont été regroupées dans une nouvelle classe RewardedAd qui diffuse des annonces avec une surface d'API semblable à 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. Un nouveau FullScreenContentListener peut être installé pour écouter les événements du cycle de vie des annonces pour ces types d'annonces, et un PaidEventListener distinct peut être installé pour suivre le moment où le service AdMob a déterminé qu'un événement payant s'est produit.

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

Nouvelles méthodes de rappel d'annonces plein écran

Méthodes FullScreenContentListener	Méthodes PaidEventListener	Méthodes UserEarnedRewardListener
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 qui ont été modifiées dans le nouveau SDK Google Mobile Ads C++. Les méthodes avec paramètres listées 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 augmente 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)