Esegui la migrazione al nuovo SDK Google Mobile Ads C++

Il rilascio dell'SDK Firebase C++ v9.1.0 introduce un nuovo SDK Google Mobile Ads C++.

L'SDK Google Mobile Ads C++ è una nuova superficie API che incorpora le principali modifiche incompatibili apportate agli SDK Firebase AdMob C++ per iOS e Android nel 2021 e nel 2022, tra cui la rimozione delle API ritirate e un nuovo flusso quando si lavora con i tipi di annunci a schermo intero.

Il vecchio SDK Firebase AdMob C++ (firebase::admob) è stato contrassegnato come deprecato e non riceverà aggiornamenti o correzioni di bug in futuro.

Sia il nuovo SDK Google Mobile Ads C++ (firebase::gma) sia il vecchio SDK Firebase AdMob C++ (firebase::admob) rimarranno parte degli archivi della build per l'SDK Firebase C++ durante il periodo di ritiro dell'SDK Firebase AdMob C++.

Rimozione delle API legacy

Le seguenti API sono state rimosse completamente dall'SDK Google Mobile Ads C++.

RewardedVideoAd

Lo spazio dei nomi RewardedVideoAd di AdMob è stato sostituito dalla classe RewardedAd. RewardedAd si comporta in modo simile a InterstitialAd, ma include un RewardedAdListener aggiuntivo per ricevere notifiche relative ai premi degli articoli.

NativeExpressAds

NativeExpressAd di AdMob era già stato contrassegnato come deprecato in ogni SDK Firebase AdMob C++. Pertanto, NativeExpressAd non è incluso nel nuovo SDK Google Mobile Ads C++.

Modifica dello spazio dei nomi dell'SDK

L'SDK è stato spostato in un nuovo spazio dei nomi e ha una nuova struttura di directory:

Spazio dei nomi firebase::gma

Le origini del nuovo SDK Google Mobile Ads C++ si trovano nello spazio dei nomi firebase::gma. Lo spazio dei nomi firebase::admob precedente è stato ritirato insieme all'SDK Firebase AdMob C++.

Struttura delle directory

I file di intestazione sono stati spostati in una nuova directory all'interno dell'archivio della build:

Raccolta

L'SDK Firebase AdMob C++ verrà fornito come libreria statica all'interno dell'archivio di build dell'SDK Firebase C++:

Migrazioni di classi, enum e struct

La tabella seguente elenca classi, enumerazioni e struct specifici che sono stati modificati o rimossi. Ecco un riepilogo:

• BannerView è stato rinominato in AdView.
• NativeAdExpressView rimosso.
• Lo spazio dei nomi RewardedVideo viene sostituito da una classe RewardedAd.
• L'enumerazione e i listener PresentationState vengono rimossi e sostituiti con i listener AdListener e FullScreenContent.

• I seguenti parametri vengono rimossi come parametri di configurazione per annuncio in AdRequests:

  • la configurazione degli ID dispositivo di test
  • il targeting degli annunci in base all'età

  Questi parametri possono ora essere configurati in RequestConfiguration, un'impostazione globale che influirà su tutti i caricamenti di annunci successivi.

Inizializzazione dell'SDK

Ogni funzione di inizializzazione dell'SDK Google Mobile Ads C++ restituisce immediatamente due indicatori di stato:

• Un parametro out facoltativo indica se si è verificato un errore di dipendenza prima dell'inizio del processo di inizializzazione.

• Il parametro restituito è un riferimento a un firebase::Future. Future contiene i risultati dell'inizializzazione asincrona degli adattatori di mediazione sul dispositivo.

Sebbene l'SDK Google Mobile Ads per C++ possa essere richiamato per caricare gli annunci pubblicati da AdMob non appena viene restituita la funzione di inizializzazione, altre reti pubblicitarie non pubblicano annunci finché l'adattatore di mediazione corrispondente non è stato inizializzato completamente. Questa procedura viene eseguita in modo asincrono. Pertanto, se utilizzi la mediazione degli annunci nella tua applicazione, ti consigliamo di attendere la risoluzione del problema Future prima di tentare di caricare gli annunci.

Prima

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

Dopo

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

Modifiche a AdSize entro AdView

AdSize ora contiene membri statici delle dimensioni comuni degli annunci banner e supporta le dimensioni degli annunci AnchorAdaptive e InlineAdaptive, che hanno un'altezza dinamica in base alla larghezza specificata e all'orientamento attuale dello schermo.

Prima

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

Dopo

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 e configurazione globale

Gli ID dispositivo di test, TagForChildDirectedTreatment e TagForUnderAgeOfConsent (precedentemente gestiti in base alla data di nascita) sono stati rimossi da AdRequest e ora fanno parte di un RequestConfiguration globale. Le applicazioni possono richiamare firebase::gma::SetRequestConfiguration() all'inizio del ciclo di vita dell'applicazione per configurare questi valori. Tutte le successive operazioni di caricamento degli annunci rispetteranno queste impostazioni una volta configurate.

firebase::gma::AdRequest esiste ancora perché fornisce informazioni contestuali per il caricamento delle pubblicità, tra cui parole chiave e un URL dei contenuti facoltativo.

La struttura in stile C di AdMob AdRequest è stata sostituita da una classe con metodi che offrono una migliore esperienza utente durante la definizione e l'aggiunta alle varie liste di informazioni.

Ecco le modifiche più importanti apportate a AdRequest:

• Ora gli extra sono associati a un nome di classe dell'adattatore di mediazione. Gli extra inviati al servizio AdMob devono utilizzare il nome della classe predefinita come definito di seguito.
• Quando richiedono un annuncio, le app possono trasmettere un URL dei contenuti che pubblicano. In questo modo, il targeting per parola chiave può abbinare l'annuncio ad altri contenuti visualizzati.

Prima

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.

Dopo

// 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 ora restituisce un Future contenente un oggetto AdResult per tutti i tipi di annuncio AdView, InterstitialAd e RewardedAd. Il metodo AdResult::is_successful restituisce true se la richiesta di annuncio è stata evasa correttamente o false in caso contrario.

In caso di errore, AdResult contiene un oggetto AdError con informazioni a livello di servizio sul problema, tra cui il codice di errore, il messaggio di errore e le stringhe di dominio.

Prima

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

Dopo

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 eventi entro AdView

La classe BannerView::Listener di AdMob è stata sostituita da due classi listener distinte nell'SDK Google Mobile Ads C++:

• AdListener monitora il ciclo di vita degli annunci e gli eventi di interazione degli utenti.
• AdViewBoundingBoxListener viene richiamato quando AdView viene ridimensionato o spostato.

Mapping dei callback OnPresentationStateChanged di AdMob Google Mobile Ads

Il tipo enumerato firebase::admob::BannerView::PresentationState e il metodo listener OnPresentationStateChanged non sono inclusi nel nuovo SDK Google Mobile Ads C++.

Di seguito sono riportati modi alternativi per rilevare le modifiche dello stato della presentazione nel ciclo di vita di un AdView:

RewardedAd ora è un corso

L'SDK Firebase AdMob C++ ritirato facilitava gli annunci con premio tramite una raccolta di funzioni nello spazio dei nomi firebase::admob::rewarded_ad. Queste funzioni sono state unite in una nuova classe RewardedAd che pubblica annunci con una superficie API simile a InterstitialAd (vedi la sezione successiva).

Ascoltatori di InterstitialAd e RewardedAd

Sia gli annunci interstitial che gli annunci con premio sono considerati annunci a schermo intero. È possibile installare un nuovo FullScreenContentListener per ascoltare gli eventi del ciclo di vita della pubblicità per questi tipi di annunci e un PaidEventListener separato per monitorare quando il servizio AdMob ha ritenuto che si sia verificato un evento a pagamento.

RewardedAd ha un listener aggiuntivo per monitorare gli eventi premio guadagnati dagli utenti.

Nuovi metodi di callback degli annunci a schermo intero

Metodi modificati/rimossi/sostituiti

La tabella seguente elenca i metodi specifici modificati nel nuovo SDK Google Mobile Ads C++. I metodi con i parametri elencati rimangono, ma le relative firme sono cambiate.