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 de 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 de 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 do diretório

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 será fornecido como uma biblioteca estática no arquivo de build do SDK do Firebase para C++:

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 (enum)	AdSize::Type (enum)
BannerView	AdView
BannerView::Listener	AdListener AdViewBoundingBoxListener PaidEventListener
BannerView::Position	AdView::Position
BannerView::PresentationState	Removido
ChildDirectedTreatmentState	RequestConfiguration::TagForChildDirectedTreatment
Gender (enum)	Removido
InterstitialAd::Listener	FullScreenContentListener PaidEventListener
KeyValuePair	Removido
NativeExpressAdView	Removido
PollableRewardListener	Removido
RewardItem	AdReward
RewardedVideoAd (namespace)	RewardedAd (classe)
RewardedVideoAd::Listener	FullScreenContentListener PaidEventListener UserEarnedRewardListener
AdMobError (enum)	AdErrorCode (enum)
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 de 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.

Mapeamentos de Google Mobile Ads para chamadas de retorno OnPresentationStateChanged da AdMob

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:

firebase::admob::BannerView::Listener OnPresentationStateChanged evento	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)