Esegui la migrazione al nuovo SDK C++ per gli annunci per dispositivi mobili di Google

Il rilascio dell'SDK Firebase C++ v9.1.0 introduce un nuovo SDK C++ per gli annunci per dispositivi mobili di Google.

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

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

Sia il nuovo SDK C++ di Google Mobile Ads ( firebase::gma ) che il vecchio SDK C++ di Firebase AdMob ( firebase::admob ) rimarranno parte degli archivi di build per l'SDK di Firebase C++ durante la finestra di deprecazione dell'SDK di Firebase AdMob C++.

Rimozione dell'API legacy

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

RewardedVideoAd

Lo spazio dei nomi RewardedVideoAd di AdMob è stato sostituito con la classe RewardedAd . RewardedAd si comporta in modo simile a InterstitialAd ma include un RewardedAdListener aggiuntivo per ricevere la notifica dei premi degli articoli.

NativeExpressAds

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

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 C++ per gli annunci per dispositivi mobili di Google si trovano nello spazio dei nomi firebase::gma . Il vecchio spazio dei nomi firebase::admob è stato deprecato insieme all'SDK Firebase AdMob C++.

Struttura delle directory

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

Biblioteca

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

Migrazioni di classi, enumerazioni e strutture

La tabella seguente elenca classi, enumerazioni e strutture specifiche che sono state modificate o rimosse. Ecco un riepilogo:

• BannerView viene rinominato AdView .
• NativeAdExpressView viene rimosso.
• Lo spazio dei nomi RewardedVideo viene sostituito con 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 dei dispositivi di test
  • la targetizzazione degli annunci pubblicitari in base all'età

  Invece, questi parametri ora possono essere configurati in RequestConfiguration , un'impostazione globale che influenzerà tutti i successivi caricamenti di annunci.

Inizializzazione dell'SDK

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

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

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

Sebbene l'SDK C++ di Google Mobile Ads possa essere richiamato per caricare gli annunci pubblicati da AdMob non appena viene ripristinata la funzione di inizializzazione, altre reti pubblicitarie non pubblicheranno annunci finché l'adattatore di mediazione corrispondente non sarà stato completamente inizializzato. Questo processo avviene in modo asincrono. Pertanto, se utilizzi la mediazione annunci nella tua applicazione, ti consigliamo di attendere la risoluzione del Future prima di tentare di caricare eventuali 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 AdSize in AdView

AdSize ora contiene membri statici delle comuni dimensioni degli annunci banner e supporta le dimensioni degli annunci AnchorAdaptive e InlineAdaptive che hanno un'altezza dinamica basata sulla larghezza specificata e sull'orientamento corrente 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 RequestConfiguration globale. Le applicazioni possono richiamare firebase::gma::SetRequestConfiguration() nelle prime fasi 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 poiché fornisce informazioni contestuali per il caricamento degli annunci pubblicitari, incluse parole chiave e un URL di contenuto opzionale.

La struttura in stile C AdRequest di AdMob è stata sostituita con una classe con metodi che forniscono una migliore esperienza utente durante la definizione e l'aggiunta ai vari elenchi di informazioni.

Di seguito sono riportate le modifiche più importanti AdRequest :

• Gli extra sono ora associati al nome di una classe dell'adattatore di mediazione. Gli extra inviati al servizio AdMob devono utilizzare il nome della classe predefinito come definito di seguito.
• Quando richiedono un annuncio, le app possono trasmettere un URL del contenuto che stanno offrendo. Ciò consente al targeting per parole chiave di abbinare l'annuncio con 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 annunci AdView , InterstitialAd e RewardedAd . Il metodo AdResult::is_successful restituisce true se la richiesta di annuncio è stata soddisfatta correttamente, altrimenti false .

In caso di errore, AdResult contiene un oggetto AdError con informazioni sul livello di servizio relative al problema, inclusi 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.
      }
    }
  }
}

Eventi AdListener all'interno di AdView

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

• AdListener tiene traccia del ciclo di vita dell'annuncio e degli eventi di interazione dell'utente.
• AdViewBoundingBoxListener viene richiamato quando AdView viene ridimensionato o spostato.

AdMob OnPresentationStateChanged richiama le mappature degli annunci per dispositivi mobili di Google

Il tipo enumerato firebase::admob::BannerView::PresentationState e il metodo listener OnPresentationStateChanged non sono inclusi nel nuovo SDK C++ per gli annunci per dispositivi mobili di Google.

Di seguito sono riportati modi alternativi per rilevare i cambiamenti dello stato di presentazione nel ciclo di vita di un AdView :

RewardedAd è ora una classe

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

Ascoltatori 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 dell'annuncio per questi tipi di annunci ed è possibile installare un PaidEventListener separato per monitorare quando il servizio AdMob ha ritenuto che si sia verificato un evento a pagamento.

RewardedAd dispone di un ascoltatore aggiuntivo per monitorare gli eventi di ricompensa guadagnati dagli utenti.

Nuovi metodi di richiamata degli annunci a schermo intero

Metodi modificati/rimossi/sostituiti

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