Migrar para o novo SDK dos anúncios para dispositivos móveis do Google para C++

A versão v9.1.0 do SDK do Firebase para C++ introduz um novo SDK dos anúncios para dispositivos móveis do Google para C++.

O SDK dos anúncios para dispositivos móveis do Google para C++ é uma plataforma de API nova que incorpora as principais alterações interruptivas feitas nos SDKs do Firebase para C++ da AdMob para iOS e Android em 2021 e 2022, incluindo a remoção de APIs descontinuadas e um novo fluxo ao trabalhar com tipos de anúncio de tela cheia.

O antigo SDK do Firebase para C++ da AdMob (firebase::admob) foi marcado como descontinuado e não vai receber mais atualizações ou correções de bugs.

O novo SDK dos anúncios para dispositivos móveis do Google para C++ (firebase::gma) e o antigo SDK do Firebase para C++ da AdMob (firebase::admob) vão continuar fazendo parte dos arquivos de build do SDK do Firebase para C++ durante a janela de descontinuação do SDK do Firebase para C++ da AdMob.

Remoção da API legada

As APIs a seguir foram inteiramente removidas do SDK dos anúncios para dispositivos móveis do Google para C++.

`RewardedVideoAd`

O namespace RewardedVideoAd da AdMob foi substituído pela classe RewardedAd. RewardedAd se comporta de maneira semelhante a InterstitialAd, mas inclui um RewardedAdListener adicional para receber notificações de recompensas por itens.

`NativeExpressAds`

O namespace NativeExpressAd da AdMob já foi marcado como descontinuado em cada SDK do Firebase para C++ da AdMob. Portanto, NativeExpressAd não está incluído no novo SDK dos anúncios para dispositivos móveis do Google para C++.

Alteração do namespace do SDK

O SDK foi realocado para um novo namespace e tem uma nova estrutura de diretórios:

Namespace `firebase::gma`

As origens do novo SDK dos anúncios para dispositivos móveis do Google para C++ estão no namespace firebase::gma. O namespace firebase::admob mais antigo foi descontinuado com o SDK do Firebase para C++ da AdMob.

Estrutura de diretórios

Os arquivos principais foram movidos para um novo diretório dentro do arquivo de build:

SDK do Firebase para C++ da AdMob descontinuado	Novo SDK dos anúncios para dispositivos móveis do Google para C++
`include/firebase/admob`	`include/firebase/gma`

Biblioteca

O SDK do Firebase para C++ da AdMob vai ser fornecido como uma biblioteca estática no arquivo de build do SDK do Firebase para C++:

iOS

SDK do Firebase para C++ da AdMob descontinuado	Novo SDK dos anúncios para dispositivos móveis do Google para C++
`firebase_admob.xcframework`	`firebase_gma.xcframework`

Android

SDK do Firebase para C++ da AdMob descontinuado	Novo SDK dos anúncios para dispositivos móveis do Google para C++
`libfirebase_admob.a`	`libfirebase_gma.a`

Migrações de classe, tipo enumerado e struct

A tabela abaixo apresenta classes, tipos enumerados e structs específicos que foram alterados ou removidos. Veja o resumo a seguir:

BannerView foi renomeado para AdView.
NativeAdExpressView foi removido.
O namespace RewardedVideo foi substituído por uma classe RewardedAd.
Os listeners e a enumeração PresentationState foram removidos e substituídos por listeners AdListener e FullScreenContent.
Os parâmetros a seguir foram removidos como parâmetros de configuração por anúncio em AdRequests:
- a configuração dos IDs dos dispositivos de teste;
- a segmentação de anúncios com base na idade.
Em vez disso, esses parâmetros podem ser definidos em RequestConfiguration, uma configuração global que vai afetar todos os carregamentos de anúncios subsequentes.

`firebase::admob namespace` descontinuado	Novo `firebase::gma namespace`
`AdSizeType` (tipo enumerado)	`AdSize::Type` (tipo enumerado)
`BannerView`	`AdView`
`BannerView::Listener`	`AdListener` `AdViewBoundingBoxListener` `PaidEventListener`
`BannerView::Position`	`AdView::Position`
`BannerView::PresentationState`	Removido
`ChildDirectedTreatmentState`	`RequestConfiguration::TagForChildDirectedTreatment`
`Gender` (tipo enumerado)	Removido
`InterstitialAd::Listener`	`FullScreenContentListener` `PaidEventListener`
`KeyValuePair`	Removido
`NativeExpressAdView`	Removido
`PollableRewardListener`	Removido
`RewardItem`	`AdReward`
`RewardedVideoAd` (namespace)	`RewardedAd` (classe)
`RewardedVideoAd::Listener`	`FullScreenContentListener` `PaidEventListener` `UserEarnedRewardListener`
`AdMobError` (tipo enumerado)	`AdErrorCode` (tipo enumerado)
`RewardItem`	`AdReward`

Inicialização do SDK

Cada função de inicialização do SDK dos anúncios para dispositivos móveis do Google para C++ retorna imediatamente dois indicadores de status:

Um parâmetro de saída opcional indica se um erro de dependência ocorreu antes do processo de inicialização começar.
O parâmetro de retorno é uma referência a um firebase::Future. Future contém os resultados da inicialização assíncrona dos adaptadores de mediação no dispositivo.

Embora o SDK dos anúncios para dispositivos móveis do Google para C++ possa ser invocado para carregar anúncios veiculados pela AdMob assim que a função de inicialização for retornada, outras redes de anúncios não vão veicular anúncios até que o adaptador de medição correspondente seja totalmente inicializado. Esse processo ocorre de forma assíncrona. Portanto, se você estiver usando a mediação de anúncios no seu aplicativo, recomendamos que espere até que o Future seja resolvido antes de tentar carregar anúncios.

Antes

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

Depois

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

Alterações em `AdSize` dentro de `AdView`

AdSize agora contém membros estáticos com tamanhos de anúncio de banner comuns, e é compatível com tamanhos de anúncios AnchorAdaptive e InlineAdaptive, que têm uma altura dinâmica com base na largura especificada e na orientação atual da tela.

Constantes estáticas `AdSize` adicionadas a `firebase::gma::AdSize`.
`AdSize::kBanner`	Tamanho do anúncio de banner da Associação de Marketing para Dispositivos Móveis (MMA, na sigla em inglês) (320 x 50 pixels de densidade independente)
`AdSize::kFullBanner`	Tamanho do anúncio de banner completo do Interactive Advertising Bureau (IAB) (468 x 60 pixels de densidade independente)
`AdSize::kLargeBanner`	Versão mais alta do `kBanner`, normalmente 320 x 100
`AdSize::kLeaderboard`	Tamanho do anúncio de cabeçalho do Interactive Advertising Bureau (IAB) (728 x 90 pixels de densidade independente)
`AdSize::kMediumRectangle`	Tamanho do anúncio de retângulo médio do Interactive Advertising Bureau (IAB) (300 x 250 pixels de densidade independente)

Métodos estáticos em `firebase::gma::AdSize` para ajudar a criar instâncias de `AdSize`
`GetLandscapeAnchoredAdaptiveBannerAdSize`	Cria um `AdSize` com a largura escolhida e com a altura otimizada pelo Google para criar um anúncio de banner no modo paisagem.
`GetPortraitAnchoredAdaptiveBannerAdSize`	Cria um `AdSize` com a largura escolhida e com a altura otimizada pelo Google para criar um anúncio de banner no modo retrato.
`GetCurrentOrientationAnchoredAdaptiveBannerAdSize`	Cria um `AdSize` com a largura escolhida e com a altura otimizada pelo Google para criar um anúncio de banner de acordo com a orientação atual.
`GetInlineAdaptiveBannerAdSize`	Cria um `AdSize` adequado para anúncios de banner com uma altura máxima. Com esse `AdSize`, os servidores do Google podem escolher um tamanho de anúncio ideal com altura menor ou igual à altura máxima especificada.
`GetLandscapeInlineAdaptiveBannerAdSize`	Cria um `InlineAdaptive` `AdSize` com a largura especificada e a altura do dispositivo em modo paisagem.
`GetPortraitInlineAdaptiveBannerAdSize`	Cria um `InlineAdaptive` `AdSize` com a largura especificada e a altura do dispositivo em modo retrato.
`GetCurrentOrientationInlineAdaptiveBannerAdSize`	Um método prático para retornar `InlineAdaptive` `AdSize` considerando a orientação atual da interface em relação a uma largura específica.

Antes

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

Depois

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 configuração global

Os IDs de dispositivos de teste, TagForChildDirectedTreatment e TagForUnderAgeOfConsent, anteriormente processados por aniversário, foram removidos de AdRequest e agora fazem parte de um RequestConfiguration global. Os aplicativos podem invocar firebase::gma::SetRequestConfiguration() no início do ciclo de vida do aplicativo para configurar esses valores. Todas as operações de carregamento de anúncios subsequentes vão respeitar essas configurações quando forem definidas.

firebase::gma::AdRequest ainda existe porque fornece informações contextuais para o carregamento de anúncios, incluindo palavras-chave e um URL de conteúdo opcional.

O struct AdRequest no estilo C da AdMob foi substituído por uma classe com métodos que oferecem uma experiência do usuário melhor durante a definição e anexação às diversas listas de informações.

Veja algumas mudanças importantes em AdRequest:

Os extras agora estão associados a um nome de classe do adaptador de mediação. Os extras enviados ao serviço da AdMob precisam usar o nome de classe padrão, como definido abaixo.
Ao solicitar um anúncio, os apps podem transmitir o URL do conteúdo que estiverem veiculando. Dessa forma a segmentação por palavras-chave pode fazer uma correspondência ao anúncio que tiver outros conteúdos em exibição.

Antes

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.

Depois

// 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 agora retorna um Future contendo um objeto AdResult para todos os tipos de anúncios de AdView, InterstitialAd e RewardedAd. O método AdResult::is_successful vai retornar true se a solicitação do anúncio tiver sido atendida, ou false em caso negativo.

Em caso de falha, AdResult contém um objeto AdError com informações de nível de serviço sobre o problema, incluindo o código do erro, a mensagem de erro e as strings de domínio.

Antes

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

Depois

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

Eventos `AdListener` dentro de `AdView`

A classe BannerView::Listener da AdMob foi substituída por duas classes diferentes de listener no SDK dos anúncios para dispositivos móveis do Google para C++:

AdListener rastreia os eventos de ciclo de vida do anúncio e de interação com o usuário.
AdViewBoundingBoxListener é invocado quando AdView é redimensionado ou movido.

Callback `OnPresentationStateChanged` da AdMob: mapeamento de anúncios para dispositivos móveis do Google

O tipo enumerado firebase::admob::BannerView::PresentationState e o método listener OnPresentationStateChanged não estão incluídos no novo SDK dos anúncios para dispositivos móveis do Google para C++.

Consulte a seguir maneiras alternativas de detectar mudanças de estado da apresentação no ciclo de vida de um AdView:

Evento `firebase::admob::BannerView::Listener OnPresentationStateChanged`	Contraparte `firebase::gma::AdListener`
`kPresentationStateHidden`	Quando `AdListener::OnAdClosed` é invocado ou quando `AdView::Hide()` conclui a operação assíncrona
`kPresentationStateVisibleWithoutAd`	Nenhuma. A tentativa de invocar um `AdView` descarregado `AdView::Show()` vai resultar em erro.
`kPresentationStateVisibleWithAd`	Quando `AdListener::OnAdOpened` é invocado ou quando `AdView::Show()` conclui a operação assíncrona com um anúncio
`kPresentationStateOpenedPartialOverlay`	Consulte a caixa delimitadora depois que `AdListener::OnAdOpened()` for invocado para determinar o tamanho e a posição do anúncio que está sendo exibido. Como alternativa, consulte a posição de `AdView` e `AdSize` e/ou monitore a caixa delimitadora com `AdViewBoundingBoxListener`.
`kPresentationStateCoveringUI`	Consulte `kPresentationStateOpenedPartialOverlay` acima

`RewardedAd` agora é uma classe

O SDK descontinuado do Firebase para C++ da AdMob facilitou anúncios premiados por meio de uma coleção de funções no namespace firebase::admob::rewarded_ad. Essas funções foram unidas em uma nova classe RewardedAd, que exibe anúncios com uma plataforma de API semelhante a InterstitialAd. Consulte a seção seguinte.

Listeners `InterstitialAd` e `RewardedAd`

Tanto os anúncios intersticiais quanto os anúncios premiados são considerados anúncios de tela cheia. Um novo FullScreenContentListener pode ser instalado para detectar eventos de ciclo de vida de publicidade para esses tipos de anúncios, e um PaidEventListener separado pode ser instalado para rastrear quando o serviço da AdMob considerar que um evento pago ocorreu.

RewardedAd tem um listener adicional para monitorar eventos de recompensas recebidas pelo usuário.

Novos métodos de callback de anúncios em tela cheia

Métodos `FullScreenContentListener`	Métodos `PaidEventListener`	Métodos `UserEarnedRewardListener`
`OnAdClicked`	`OnPaidEvent`	`OnUserEarnedReward`
`OnAdDismissedFullScreenContent`
`OnAdFailedToShowFullScreenContent`
`OnAdImpression`
`OnAdShowedFullScreenContent`

Métodos alterados/removidos/substituídos

A tabela abaixo lista os métodos específicos alterados no novo SDK dos anúncios para dispositivos móveis do Google para C++. Os métodos com parâmetros listados permanecem, mas as assinaturas deles mudaram.

Classe	API do SDK do Firebase para C++ da AdMob	API do SDK dos anúncios para dispositivos móveis do Google para C++	Observações
`BannerView`	`MoveTo`	`AdView::SetPosition`
	`presentation_state`	Removido	Processado por eventos de `AdViewListener` e resultados futuros de `AdView::Show` e `AdView::Hide`.
	`SetListener`	`AdView::SetAdListener` `AdView::SetBoundingBoxListener` `AdView::SetPaidEventListener`	O novo design do listener aumenta a fidelidade da detecção de eventos de ciclo de vida de `AdView`.
	`Listener::OnPresentationStateChanged`	Removido	Consulte `BannerView::SetListener`, acima.
	`Listener::OnBoundingBoxChanged`	`AdViewBoundingBoxListener::OnBoundingBoxChanged`
InterstitialAd	`Initialize(AdParent parent, const char* ad_unit_id)`	`Initialize(AdParent parent)`	O parâmetro `ad_unit_id` agora faz parte da operação `LoadAd`.
	`LoadAd(const AdRequest& request)`	`LoadAd(const char* ad_unit_id, const AdRequest& request)`
	`presentation_state`	Removido	A enumeração `presentation_state` foi removida. Use `FullScreenContentListener`.
	`SetListener`	`SetFullScreenContentListener` `SetPaidEventListener`
	`Destroy`	Removido	A limpeza dos recursos agora faz parte do destrutor `RewardedAd`.
`RewardedAd` (formalmente `RewardedVideoAd`)	`Initialize`	`Initialize(AdParent parent)`	`AdParent` era transmitido para `Show`, mas agora faz parte da inicialização.
	`presentation_state`	Removido	A enumeração `presentation_state` foi removida. Use `FullScreenContentListener`.
	`SetListener`	`SetFullScreenContentListener` `SetPaidEventListener` `Show`	Um listener `UserEarnedReward` também é definido ao exibir um `RewardedAd`. Veja abaixo.
	`Show(AdParent parent)`	`Show(UserEarnedRewardListener* listener)`

Migrar para o novo SDK dos anúncios para dispositivos móveis do Google para C++

Remoção da API legada

RewardedVideoAd

NativeExpressAds

Alteração do namespace do SDK

Namespace firebase::gma

Estrutura de diretórios

Biblioteca

iOS

Android

Migrações de classe, tipo enumerado e struct

Inicialização do SDK

Antes

Depois

Alterações em AdSize dentro de AdView

Antes

Depois

AdRequest e configuração global

Antes

Depois

AdResults

Antes

Depois

Eventos AdListener dentro de AdView

Callback OnPresentationStateChanged da AdMob: mapeamento de anúncios para dispositivos móveis do Google

RewardedAd agora é uma classe

Listeners InterstitialAd e RewardedAd

Novos métodos de callback de anúncios em tela cheia

Métodos alterados/removidos/substituídos

`RewardedVideoAd`

`NativeExpressAds`

Namespace `firebase::gma`

Alterações em `AdSize` dentro de `AdView`

`AdRequest` e configuração global

`AdResults`

Eventos `AdListener` dentro de `AdView`

Callback `OnPresentationStateChanged` da AdMob: mapeamento de anúncios para dispositivos móveis do Google

`RewardedAd` agora é uma classe

Listeners `InterstitialAd` e `RewardedAd`