Vídeo premiado

Use a AdMob para exibir vídeos premiados nos apps do C++ via mediação da AdMob.

Neste guia, você aprenderá a solicitar e exibir um vídeo premiado, determinar quando os vídeos premiados estão disponíveis e premiar o usuário.

Pré-requisitos

Antes de começar a interagir com a API C++ de vídeos premiados, inclua adaptadores e SDKs da rede de mediação no app a partir do qual você quer veicular vídeos premiados. Confira as etapas sobre como adicionar mediação de vídeos premiados ao app no guia de vídeos premiados de editores para iOS e Android.

Se esta é a primeira vez que você configura a AdMob e o Firebase no app C++, consulte o guia Primeiros passos da AdMob C++ para instruções passo a passo sobre como integrar o app à AdMob e ao Firebase.

Interagir com o namespace rewarded_video

O namespace rewarded_video contém métodos para exibir vídeos premiados por meio do SDK dos anúncios para dispositivos móveis do Google. Ao contrário dos anúncios de banner e intersticiais, que têm objetos próprios, os vídeos premiados são controlados usando métodos estáticos no namespace rewarded_video.

Para acessar o namespace rewarded_video, adicione a seguinte inclusão ao código C ++ do seu aplicativo:

#include "firebase/admob/rewarded_video.h"

Etapas básicas para interagir com o namespace rewarded_video:

  1. Chame Initialize() para inicializar a biblioteca e os adaptadores de mediação:

    firebase::admob::rewarded_video::Initialize();
    
  2. Agora que a biblioteca e os adaptadores de mediação foram inicializados, você está pronto para chamar LoadAd() para carregar um vídeo premiado:

    firebase::admob::AdRequest my_ad_request;
    // Set some or all of the member variables in the AdRequest struct.
    firebase::admob::rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID", my_ad_request);
    

    Consulte um exemplo de segmentação e personalização de solicitações de anúncios em Criar uma solicitação de anúncio da AdMob.

  3. Depois que o vídeo premiado for carregado, chame Show() para exibir o vídeo ao usuário:

    // my_ad_parent is a reference to an iOS UIView or an Android Activity. This is
    // the parent UIView or Activity of the rewarded video.
    firebase::admob::rewarded_video::Show(my_ad_parent);
    
  4. Repita as etapas 2 e 3 conforme necessário.

  5. Chame Pause() para pausar qualquer processamento em segundo plano associado ao vídeo premiado:

    firebase::admob::rewarded_video::Pause();
    

    Chame esse método sempre que o mecanismo C++ faz uma pausa ou o app perde o foco.

  6. Chame Resume() para retomar a partir de uma pausa, por exemplo, quando o usuário retornar ao seu app a partir do Google Play:

    firebase::admob::rewarded_video::Resume();
    
  7. Quando terminar de exibir anúncios em vídeo premiados no seu aplicativo, chame Destroy() para limpar e cancelar a alocação de todos os recursos usados pelo namespace de vídeo premiado:

    firebase::admob::rewarded_video::Destroy();
    

As etapas acima destacam as chamadas de método básicas que o app precisa usar durante o carregamento e a exibição de um vídeo premiado. A prática recomendada, no entanto, é monitorar o status de conclusão das chamadas de métodos anteriores antes de chamá-los. Na próxima seção são descritas as etapas para usar Futures a fim de determinar o status de conclusão das chamadas de método anteriores do namespace rewarded_video.

Usar Futures para monitorar o status de conclusão das chamadas de método

Futures oferecem uma maneira de determinar o status de conclusão das chamadas de método anteriores do namespace rewarded_video. Quando uma chamada é feita para o método rewarded_video::Initialize(), por exemplo, um novo Future é criado e retornado. Consulte firebase::Future para mais detalhes. O status do Future pode ser pesquisado pelos apps para determinar quando a inicialização foi concluída. Após a conclusão do Future, você estará pronto para carregar o vídeo premiado.

A maioria dos métodos no namespace rewarded_video têm um método de "último resultado" correspondente que os apps podem usar para recuperar o Future mais recente de uma determinada ação. O método Initialize(), por exemplo, tem um método chamado InitializeLastResult() que retorna o Future para a chamada mais recente para Initialize():

if (firebase::admob::rewarded_video::InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    firebase::admob::rewarded_video::InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  firebase::admob::rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID",
      my_ad_request);
}

Use o método LoadAdLastResult() para receber um Future que representa o status da última chamada para o método LoadAd(). Se o status for "concluído", exiba o vídeo premiado no próximo ponto de parada natural do app:

if (firebase::admob::rewarded_video::LoadAdLastResult().status() ==
    firebase::kFutureStatusComplete &&
    firebase::admob::rewarded_video::LoadAdLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  // my_ad_parent is a reference to an iOS UIView or an Android Activity.
  // This is the parent UIView or Activity of the rewarded video.
  firebase::admob::rewarded_video::Show(my_ad_parent);
}

Usar um listener para ser notificado dos eventos do ciclo de vida do anúncio

O namespace rewarded_video da AdMob fornece uma classe Listener abstrata que você pode estender e passar para o método SetListener() para ser notificado sobre os prêmios e as alterações no estado das apresentações de vídeo premiado.

Exemplo de implementação de uma classe que estende a classe abstrata Listener:

// A simple listener that logs changes to rewarded video state.
class LoggingRewardedVideoListener
    : public firebase::admob::rewarded_video::Listener {
 public:
  LoggingRewardedVideoListener() {}
  void OnRewarded(firebase::admob::rewarded_video::RewardItem reward) override {
    LogMessage("Rewarding user with %f %s.", reward.amount,
               reward.reward_type.c_str());
  }
  void OnPresentationStateChanged(
      firebase::admob::rewarded_video::PresentationState state) override {
    LogMessage("Rewarded video PresentationState has changed to %d.", state);
  }
};

// After calling Initialize and waiting for the Initialize future to complete
// successfully, set the listener.
LoggingRewardedVideoListener rewarded_video_listener;
firebase::admob::rewarded_video::SetListener(&rewarded_video_listener);

Pesquisar prêmios

O namespace rewarded_video também fornece PollableRewardListener, uma classe que você pode instanciar e passar para o método SetListener(). Essa classe fornece uma opção alternativa para acessar prêmios sem precisar estender a classe Listener abstrata.

O listener baseado em pesquisa usa uma fila para manter os prêmios concedidos pelo SDK de anúncios para dispositivos móveis que podem ser recuperada mais tarde. O método PollReward(RewardItem* reward) do PollableRewardListener exibe o prêmio mais antigo na fila e copia os dados dele para o struct RewardItem fornecido.

Exemplo de implementação para a pesquisa de prêmios usando a classe rewarded_video::PollableRewardListener:

// After calling Initialize and waiting for the Initialize future to complete
// successfully, instantiate a PollableRewardListener object and set the listener.
firebase::admob::rewarded_video::PollableRewardListener* listener =
    new firebase::admob::rewarded_video::PollableRewardListener();

// Pass the PollableRewardListener object to the SetListener method.
firebase::admob::rewarded_video::SetListener(listener);

...
// Display the rewarded videos to users so they can earn rewards.
...

// Declare a RewardItem struct. Pass this RewardItem struct by reference to
// the PollReward method.
firebase::admob::rewarded_video::RewardItem reward;
// Call the PollReward method to see if a reward is available.
while (listener->PollReward(&reward)) {
  // A reward is available. Do something with the reward.
  printf("Reward user with %f %s.", reward.amount, reward.reward_type);
}

Exemplo de loop de jogo simples

Este é um loop de jogo simples que usa uma máquina de estado para acompanhar chamadas de método para o namespace rewarded_video:

namespace rewarded_video = firebase::admob::rewarded_video;

enum State {
  kNextStepInitialize,
  kNextStepLoadAd,
  kNextStepShowAd,
  kNextStepRewardUser,
  kNextStepRestartGame
}

// Instantiate a PollableRewardListener object.
firebase::admob::rewarded_video::PollableRewardListener* listener =
    new firebase::admob::rewarded_video::PollableRewardListener();

State state = kNextStepInitialize;
for ( ; ; ) /* game loop */ {
  switch (state) {
    case kNextStepInitialize:
      rewarded_video::Initialize();
      state = kNextStepLoadAd;
      break;
    case kNextStepLoadAd:
      if (rewarded_video::InitializeLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::InitializeLastResult().error() ==
          firebase::admob::kAdMobErrorNone) {
        // Pass the PollableRewardListener object to the SetListener method.
        firebase::admob::rewarded_video::SetListener(listener);
        rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID",
                               my_ad_request);
      }
      state = kNextStepShowAd;
      break;
    case kNextStepShowAd:
      if (rewarded_video::LoadAdLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::LoadAdLastResult().error() ==
          firebase::admob::kAdMobErrorNone) {
        rewarded_video::Show(my_ad_parent);
      }

      if (rewarded_video::ShowLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::ShowLastResult().error() ==
          firebase::admob::kAdMobErrorNone &&
          rewarded_video::presentation_state() ==
          rewarded_video::kPresentationStateHidden) {
        // If the rewarded video has been displayed to the user and
        // the user closed the ad, then reward the user.
        state = kNextStepRewardUser;
      }
      break;
    case kNextStepRewardUser:
      firebase::admob::rewarded_video::RewardItem reward;
      // Call the PollReward method to see if a reward is available.
      while (listener->PollReward(&reward)) {
        // A reward is available. Do something with the reward.
        printf("Reward user with %f %s.", reward.amount, reward.reward_type);
      }
      state = kNextStepRestartGame;
      break;
    case kNextStepRestartGame:
      // restart game
      break;
  }

  // render game
}

A seguir

Consulte os guias de primeiros passos Vídeo premiado para iOS e Vídeo premiado para Android para mais informações sobre anúncios em vídeo premiados.