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

O lançamento do SDK C++ do Firebase v9.1.0 apresenta um novo SDK C++ dos anúncios para dispositivos móveis do Google.

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

O antigo SDK C++ da AdMob do Firebase ( firebase::admob ) foi marcado como obsoleto e não receberá nenhuma atualização ou correção de bug no futuro.

Tanto o novo SDK C++ dos anúncios para dispositivos móveis do Google ( firebase::gma ) quanto o antigo SDK C++ da AdMob do Firebase ( firebase::admob ) permanecerão como parte dos arquivos de compilação do SDK C++ do Firebase durante a janela de suspensão de uso do SDK C++ da AdMob do Firebase.

Remoção de API legada

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

RewardedVideoAd

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

NativeExpressAds

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

Alteração do namespace do SDK

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

Namespace firebase::gma

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

Estrutura de diretório

Os arquivos de cabeçalho foram movidos para um novo diretório dentro do arquivo de compilação:

Biblioteca

O SDK C++ da AdMob do Firebase será fornecido como uma biblioteca estática no arquivo de compilação do SDK C++ do Firebase:

Migrações de classe, enum e struct

A tabela abaixo lista classes, enumerações e estruturas específicas que foram alteradas ou removidas. Aqui está um resumo:

• BannerView foi renomeado para AdView .
• NativeAdExpressView foi removido.
• O namespace RewardedVideo é substituído por uma classe RewardedAd .
• A enumeração e os ouvintes PresentationState são removidos e substituídos pelos ouvintes AdListener e FullScreenContent .

• Os seguintes parâmetros são removidos como parâmetros de configuração por anúncio em AdRequests :

  • a configuração de IDs de dispositivos de teste
  • a segmentação de anúncios com base na idade

  Em vez disso, esses parâmetros agora podem ser configurados em RequestConfiguration , que é uma configuração global que afetará todos os carregamentos de anúncios subsequentes.

Inicialização do SDK

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

• Um parâmetro out opcional informa se ocorreu um erro de dependência antes do início do processo de inicialização.

• O parâmetro de retorno é uma referência a firebase::Future . O Future contém os resultados da inicialização assíncrona dos adaptadores de mediação no dispositivo.

Embora o SDK C++ dos anúncios para dispositivos móveis do Google possa ser invocado para carregar anúncios veiculados pela AdMob assim que a função de inicialização retornar, outras redes de anúncios não veicularão anúncios até que o adaptador de mediação correspondente tenha sido totalmente inicializado. Esse processo ocorre de forma assíncrona. Portanto, se você estiver usando a mediação de anúncios em seu aplicativo, recomendamos que você aguarde a resolução do Future antes de tentar carregar qualquer anúncio.

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 no AdSize no AdView

AdSize agora contém membros estáticos de tamanhos de anúncios de banner comuns e oferece suporte a tamanhos de anúncios AnchorAdaptive e InlineAdaptive que têm uma altura dinâmica com base na largura fornecida e na orientação atual da tela.

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

IDs de dispositivos de teste, TagForChildDirectedTreatment e TagForUnderAgeOfConsent (anteriormente tratados 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 subsequentes de carregamento de anúncios respeitarão essas configurações depois de configuradas.

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

A estrutura AdRequest estilo C da AdMob foi substituída por uma classe com métodos que proporcionam uma melhor experiência do usuário ao definir e anexar às diversas listas de informações.

Aqui estão alterações notáveis AdRequest :

• Os extras agora estão associados a um nome de classe do adaptador de mediação. Os extras enviados ao serviço AdMob devem usar o nome de classe padrão conforme definido abaixo.
• Ao solicitar um anúncio, os aplicativos podem transmitir um URL do conteúdo que estão veiculando. Isso permite que a segmentação por palavras-chave corresponda ao anúncio com outro conteúdo exibido.

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úncio AdView , InterstitialAd e RewardedAd . O método AdResult::is_successful retorna true se a solicitação de anúncio foi atendida com sucesso ou false se não.

Em caso de falha, o AdResult contém um objeto AdError com informações de nível de serviço sobre o problema, incluindo o código de erro, a mensagem de erro e as sequências 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 no AdView

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

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

Mapeamentos de anúncios para celular do Google de retorno de chamada AdMob OnPresentationStateChanged

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

A seguir estão formas alternativas de detectar mudanças no estado de apresentação no ciclo de vida de um AdView :

RewardedAd agora é uma classe

O SDK C++ da AdMob do Firebase obsoleto facilitou anúncios premiados por meio de uma coleção de funções no namespace firebase::admob::rewarded_ad . Essas funções foram reunidas em uma nova classe RewardedAd que veicula anúncios com uma superfície de API semelhante à InterstitialAd (veja a próxima seção).

Ouvintes InterstitialAd e RewardedAd

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

RewardedAd tem um ouvinte adicional para monitorar eventos de recompensa ganhos pelo usuário.

Novos métodos de retorno de chamada de anúncio em tela cheia

Métodos alterados/removidos/substituídos

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