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

OBSOLETO: l'SDK Google Mobile Ads per C++ è obsoleto dal 17 giugno 2024 e non deve essere adottato nei progetti che non lo utilizzano già. Entrerà in End-of-Maintenance (EoM) il 17 giugno 2025. Tieni presente che le versioni dell'SDK rilasciate prima della data di fine mese continueranno a funzionare, ma non verranno rilasciate ulteriori correzioni di bug o modifiche dopo questa data.

Anziché l'SDK Google Mobile Ads per C++, ti consigliamo di utilizzare gli SDK per iOS e Android disponibili da AdMob. Per ricevere assistenza, contatta il forum tecnico dell'SDK Google Mobile Ads.

La versione 9.1.0 dell'SDK Firebase C++ introduce un nuovo SDK Google Mobile Ads per C++.

L'SDK Google Mobile Ads C++ è una nuova API che incorpora le modifiche sostanziali apportate agli SDK Firebase AdMob C++ per iOS e Android nel 2021 e nel 2022, inclusa la rimozione delle API ritirate e un nuovo flusso quando si utilizzano 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 negli archivi di compilazione 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 una notifica relativa 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

I file sorgente 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 di compilazione:

SDK Firebase AdMob C++ deprecato	Nuovo SDK Google Mobile Ads C++
include/firebase/admob	include/firebase/gma

Raccolta

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

iOS

SDK Firebase AdMob C++ deprecato	Nuovo SDK Google Mobile Ads C++
firebase_admob.xcframework	firebase_gma.xcframework

Android

SDK Firebase AdMob C++ deprecato	Nuovo SDK Google Mobile Ads C++
libfirebase_admob.a	libfirebase_gma.a

Migrazioni di classi, enum e struct

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

• Il nuovo nome di BannerView è 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 dei dispositivi di test
  • il targeting degli annunci in base all'età

  Ora questi parametri possono essere configurati in RequestConfiguration che è un'impostazione globale che influisce su tutti i caricamenti degli annunci successivi.

firebase::admob namespace in disuso	Nuovo firebase::gma namespace
AdSizeType (enum)	AdSize::Type (enum)
BannerView	AdView
BannerView::Listener	AdListener AdViewBoundingBoxListener PaidEventListener
BannerView::Position	AdView::Position
BannerView::PresentationState	Rimossa
ChildDirectedTreatmentState	RequestConfiguration::TagForChildDirectedTreatment
Gender (enum)	Rimosso
InterstitialAd::Listener	FullScreenContentListener PaidEventListener
KeyValuePair	Rimossa
NativeExpressAdView	Rimossa
PollableRewardListener	Rimossa
RewardItem	AdReward
RewardedVideoAd (spazio dei nomi)	RewardedAd (classe)
RewardedVideoAd::Listener	FullScreenContentListener PaidEventListener UserEarnedRewardListener
AdMobError (enum)	AdErrorCode (enum)
RewardItem	AdReward

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'avvio del processo di inizializzazione.

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

Sebbene l'SDK Google Mobile Ads per C++ possa essere invocato per caricare gli annunci pubblicati da AdMob non appena viene restituita la funzione di inizializzazione, le altre reti pubblicitarie non pubblicheranno annunci finché l'adattatore di mediazione corrispondente non sarà stato completamente inizializzato. Questa procedura avviene 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 in AdView

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

Costanti AdSize statiche aggiunte a firebase::gma::AdSize
AdSize::kBanner	Dimensioni degli annunci banner della Mobile Marketing Association (MMA) (pixel indipendenti dalla densità di 320 x 50)
AdSize::kFullBanner	Dimensioni degli annunci banner completi di Interactive Advertising Bureau (IAB) (468 x 60 pixel indipendenti dalla densità)
AdSize::kLargeBanner	Versione più alta di kBanner, in genere 320 x 100
AdSize::kLeaderboard	Dimensioni degli annunci leaderboard di Interactive Advertising Bureau (IAB) (728 x 90 pixel indipendenti dalla densità)
AdSize::kMediumRectangle	Dimensioni degli annunci rettangolari medi dell'Interactive Advertising Bureau (IAB) (pixel indipendenti dalla densità di 300 x 250)

Metodi statici in firebase::gma::AdSize per aiutare a creare istanze di AdSize
GetLandscapeAnchoredAdaptiveBannerAdSize	Crea un AdSize con la larghezza specificata e un'altezza ottimizzata da Google per creare un annuncio banner in modalità Orizzontale
GetPortraitAnchoredAdaptiveBannerAdSize	Crea un AdSize con la larghezza specificata e un'altezza ottimizzata da Google per creare un annuncio banner in modalità Ritratto
GetCurrentOrientationAnchoredAdaptiveBannerAdSize	Crea un AdSize con la larghezza specificata e un'altezza ottimizzata da Google per creare un annuncio banner in base all'orientamento corrente
GetInlineAdaptiveBannerAdSize	Crea un AdSize più adatto per gli annunci banner in base a un'altezza massima Questo AdSize consente ai server Google di scegliere una dimensione dell'annuncio ottimale con un'altezza inferiore o uguale a un'altezza massima specificata.
GetLandscapeInlineAdaptiveBannerAdSize	Crea un InlineAdaptive AdSize con la larghezza specificata e l'altezza in orizzontale del dispositivo
GetPortraitInlineAdaptiveBannerAdSize	Crea un InlineAdaptive AdSize con la larghezza specificata e l'altezza del dispositivo in verticale.
GetCurrentOrientationInlineAdaptiveBannerAdSize	Un metodo di utilità per restituire InlineAdaptive AdSize in base all'orientamento corrente dell'interfaccia e a una determinata larghezza.

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 (in precedenza gestiti in base alla data di nascita) sono stati rimossi da AdRequest e ora fanno parte di un RequestConfiguration globale. Le applicazioni possono invocare firebase::gma::SetRequestConfiguration() all'inizio del ciclo di vita dell'applicazione per configurare questi valori. Tutte le operazioni di caricamento degli annunci successive rispetteranno queste impostazioni una volta configurate.

firebase::gma::AdRequest continua a esistere perché fornisce informazioni contestuali per il caricamento degli annunci, tra cui parole chiave e un URL dei contenuti facoltativo.

La AdRequest struct in stile C di AdMob è stata sostituita da una classe con metodi che offrono un'esperienza utente migliore durante la definizione e l'aggiunta ai diversi elenchi di informazioni.

Ecco le modifiche principali di 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 dei contenuti che pubblicano. In questo modo, il targeting per parole chiave consente di associare 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 annunci AdView, InterstitialAd e RewardedAd. Il metodo AdResult::is_successful restituisce true se la richiesta di annuncio è stata soddisfatta o false in caso contrario.

In caso di errore, AdResult contiene un oggetto AdError con informazioni sul problema a livello di servizio, 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 in AdView

La classe BannerView::Listener di AdMob è stata sostituita da due classi di 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 invocato quando le dimensioni di AdView vengono modificate o quando viene spostato.

Mappature dei OnPresentationStateChanged callback Google Mobile Ads di AdMob

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

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

firebase::admob::BannerView::Listener OnPresentationStateChanged evento	firebase::gma::AdListener controparte
kPresentationStateHidden	Quando viene invocato AdListener::OnAdClosed o quando AdView::Hide() completa correttamente la sua operazione asincrona
kPresentationStateVisibleWithoutAd	Nessuno. Il tentativo di richiamare AdView::Show() un caricamento non eseguito AdView comporterà un errore.
kPresentationStateVisibleWithAd	Quando viene invocato AdListener::OnAdOpened o quando AdView::Show() completa la sua operazione asincrona correttamente con un annuncio
kPresentationStateOpenedPartialOverlay	Esegui una query sulla casella delimitante dopo aver invocato AdListener::OnAdOpened() per determinare le dimensioni e la posizione dell'annuncio visualizzato. In alternativa, esegui query sulla posizione di AdView e AdSize e/o monitora la casella delimitante tramite AdViewBoundingBoxListener.
kPresentationStateCoveringUI	Vedi kPresentationStateOpenedPartialOverlay sopra

RewardedAd è ora un corso

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 unite in una nuova classe RewardedAd che pubblica annunci con un'interfaccia API simile a InterstitialAd (vedi la sezione successiva).

Ascoltatori di InterstitialAd e RewardedAd

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

RewardedAd ha un listener aggiuntivo per monitorare gli eventi relativi ai premi guadagnati dagli utenti.

Nuovi metodi di callback per gli annunci a schermo intero

FullScreenContentListener metodi	PaidEventListener metodi	UserEarnedRewardListener metodi
OnAdClicked	OnPaidEvent	OnUserEarnedReward
OnAdDismissedFullScreenContent
OnAdFailedToShowFullScreenContent
OnAdImpression
OnAdShowedFullScreenContent

Metodi modificati/rimossi/sostituiri

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 relative firme sono cambiate.

Classe	API SDK Firebase AdMob C++	API SDK Google Mobile Ads per C++	Note
BannerView	MoveTo	AdView::SetPosition
	presentation_state	Rimosso	Gestito dagli eventi AdViewListener e dai risultati futuri AdView::Show e AdView::Hide.
	SetListener	AdView::SetAdListener AdView::SetBoundingBoxListener AdView::SetPaidEventListener	Il nuovo design del listener aumenta la fedeltà del rilevamento AdView degli eventi del ciclo di vita.
	Listener::OnPresentationStateChanged	Rimosso	Vedi BannerView::SetListener, sopra.
	Listener::OnBoundingBoxChanged	AdViewBoundingBoxListener::OnBoundingBoxChanged
InterstitialAd	Initialize(AdParent parent, const char* ad_unit_id)	Initialize(AdParent parent)	Il parametro ad_unit_id ora fa parte dell'operazione LoadAd.
	LoadAd(const AdRequest& request)	LoadAd(const char* ad_unit_id, const AdRequest& request)
	presentation_state	Rimosso	L'enumerazione presentation_state è stata rimossa. Utilizza FullScreenContentListener.
	SetListener	SetFullScreenContentListener SetPaidEventListener
	Destroy	Rimosso	La pulizia delle risorse ora fa parte del distruttore RewardedAd.
RewardedAd (formalmente RewardedVideoAd)	Initialize	Initialize(AdParent parent)	AdParent veniva precedentemente passato a Show, ma ora fa parte dell'inizializzazione.
	presentation_state	Rimosso	L'enumerazione presentation_state è stata rimossa. Utilizza FullScreenContentListener.
	SetListener	SetFullScreenContentListener SetPaidEventListener Show	Un ascoltatore UserEarnedReward viene definito anche quando viene mostrato un RewardedAd. Consulta quanto riportato di seguito.
	Show(AdParent parent)	Show(UserEarnedRewardListener* listener)