Anúncios premiados


Os anúncios premiados oferecem aos usuários a opção de interagir com eles em troca de recompensas no app. Este guia mostra como integrar anúncios premiados a apps Android e iOS usando o SDK de anúncios para dispositivos móveis do Google para C++.

Confira algumas histórias de sucesso do cliente: estudo de caso 1, estudo de caso 2.

Pré-requisitos

Sempre usar anúncios de teste

Ao criar e testar seus apps, use anúncios de teste em vez de anúncios de produção ativos. Sua conta poderá ser suspensa se isso não for feito.

A maneira mais fácil de carregar anúncios de teste é usar nosso ID de bloco de anúncios de teste dedicado para anúncios premiados, que varia de acordo com a plataforma do dispositivo:

  • Android: ca-app-pub-3940256099942544/5224354917
  • iOS: ca-app-pub-3940256099942544/1712485313

Eles foram configurados especialmente para retornar anúncios de teste em todas as solicitações, e você pode usá-los nos seus próprios apps durante a programação, os testes e a depuração. Não se esqueça de substituí-los pelo seu ID do bloco de anúncios antes de publicar o app.

Para mais informações sobre como os anúncios de teste do SDK para Dispositivos Móveis funcionam, consulte Anúncios de teste.

Implementação

As principais etapas para integrar anúncios premiados são:

  1. Carregue um anúncio.
  2. Registre callbacks.
  3. Exiba o anúncio e processe o evento premiado.

Configurar um RewardedAd

Os anúncios premiados são exibidos em objetos RewardedAd. Portanto, a primeira etapa para integrá-los ao seu app é criar e inicializar uma instância de RewardedAd.

  1. Adicione este cabeçalho ao código em C++ do aplicativo: 

     #include "firebase/gma/rewarded_ad.h"

  2. Declare e instancie um objeto RewardedAd: 

     firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

  3. Inicialize a instância RewardedAd usando a visualização da família transmitida para um tipo AdParent. A visualização da família é uma referência jobject da JNI a uma Activity do Android ou um ponteiro para uma UIView do iOS.

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

  4. Como alternativa a manter o futuro como uma variável, você pode verificar periodicamente o status da operação de inicialização invocando InitializeLastResult() no objeto RewardedAd. Isso pode ser útil para acompanhar o processo de inicialização no loop de jogo global.

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

Para mais informações sobre como trabalhar com firebase::Future, consulte Usar futuros para monitorar o status de conclusão de chamadas de método.

Carregar um anúncio

O carregamento de um anúncio é feito usando o método LoadAd() em um objeto RewardedAd. O método de carregamento exige que você tenha inicializado o objeto RewardedAd e que tenha o ID do bloco de anúncios e um objeto AdRequest. Um firebase::Future é retornado, que você pode usar para monitorar o estado e o resultado da operação de carregamento.

O código a seguir mostra como carregar um anúncio depois que o RewardedAd for inicializado:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

Registrar callbacks

É necessário estender a classe FullScreenContentListener para receber notificações de eventos de apresentação e ciclo de vida de anúncios premiados. Sua subclasse personalizada FullScreenContentListener pode ser registrada pelo método RewardedAd::SetFullScreenContentListener(), e ela vai receber callbacks quando o anúncio for apresentado com ou sem sucesso, bem como quando for dispensado.

O código a seguir mostra como estender a classe e atribuí-la ao anúncio:

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd é um objeto de uso único. Isso significa que, depois que um anúncio premiado é mostrado, ele não pode ser mostrado novamente. Uma prática recomendada é carregar outro anúncio premiado no método OnAdDismissedFullScreenContent() do FullScreenContentListener para que o próximo anúncio premiado comece a ser carregado assim que o anterior for dispensado.

Mostrar o anúncio e processar o evento premiado

Antes de mostrar um anúncio premiado aos usuários, você precisa apresentar uma opção explícita para que eles assistam o conteúdo do anúncio premiado em troca de uma recompensa. Os anúncios premiados precisam sempre ser uma experiência de aceitação.

Ao apresentar seu anúncio, você tem que fornecer um objeto UserEarnedReward para processar a recompensa do usuário.

O código a seguir mostra como exibir um RewardedAd:

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

Perguntas frequentes

Existe um tempo limite para a chamada de inicialização?
Após 10 segundos, o SDK de anúncios para dispositivos móveis do Google para C++ conclui o firebase::Future retornado por Initialize(), mesmo que uma rede de mediação ainda não tenha concluído a inicialização.
E se algumas redes de mediação não estiverem prontas quando eu receber o callback de inicialização?

A prática recomendada é carregar anúncios após a conclusão da inicialização do SDK. Mesmo que uma rede de mediação não esteja pronta, o SDK de anúncios para dispositivos móveis do Google para C++ ainda vai pedir um anúncio a ela. Portanto, se uma rede de mediação terminar a inicialização após o tempo limite, ela ainda poderá atender a solicitações de anúncios futuras nessa sessão.

Você pode continuar a consultar o status de inicialização de todos os adaptadores durante a sessão do app chamando GetInitializationStatus().

Como descobrir por que uma rede de mediação específica não está pronta?

AdapterStatus.description() descreve por que um adaptador não está pronto para atender a solicitações de anúncios. Consulte o código-fonte do nosso app de início rápido de exemplo no GitHub para conferir um exemplo de registro do status do adaptador de mediação.

Outros recursos

Exemplo no GitHub

  • Confira o código-fonte do nosso app de início rápido de exemplo no GitHub.