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 lors de l'utilisation de types d'annonces en plein écran.

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

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

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

Modification de l'espace de noms du SDK

Le SDK a été transféré vers un nouvel espace de noms et présente une nouvelle structure de répertoires:

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é 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:

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 répertorie les classes, les énumérations et les 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.

Initialisation du SDK

Chaque fonction d'initialisation du SDK C++ Google Mobile Ads 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 C++ Google Mobile Ads puisse être appelé pour charger des annonces diffusées par AdMob dès que la fonction d'initialisation le renvoie, les autres réseaux publicitaires ne diffusent 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 des annonces dans votre application, nous vous recommandons d'attendre la résolution de l'Future 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 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.

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 date d'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 avec 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.

Mappages Google Mobile Ads du rappel AdMob OnPresentationStateChanged

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 :

RewardedAd est désormais une classe

Le SDK Firebase AdMob C++, désormais obsolète, a permis la diffusion d'annonces avec récompense via un ensemble 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 liés aux récompenses gagnées par l'utilisateur.

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

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