Configurar anúncios premiados

Neste guia, explicamos como integrar anúncios premiados a um app Android.

Antes de começar

Antes de continuar, faça o seguinte:

• Configure o GMA Next-Gen SDK.
• Use o ID do bloco de anúncios premiado de teste /21775744923/example/rewarded.
  • Ao criar e testar seu app, use anúncios de teste em vez de anúncios de produção ativos. Se você não usar o ID do bloco de anúncios de teste, o Google poderá suspender sua conta.
  • Antes de publicar o app, substitua esse ID pelo ID do seu bloco de anúncios.
  • Para detalhes sobre os anúncios de teste do GMA Next-Gen SDK, consulte Ativar anúncios de teste.

Entender o pré-carregamento de anúncios (Beta)

O pré-carregamento de anúncios em GMA Next-Gen SDK automatiza o carregamento e o armazenamento em cache de anúncios.

O pré-carregamento de anúncios oferece os seguintes benefícios:

• Gerenciamento de referências: mantém as referências até que os anúncios sejam mostrados.
• Recarregamento automático: carrega um novo anúncio quando um é recuperado do cache.
• Tentativas gerenciadas: carrega um novo anúncio quando um não é carregado.
• Tratamento de expiração: atualiza os anúncios antes que eles expirem.
• Otimização de cache: otimiza a ordem do cache para exibir o anúncio de maior prioridade.

Iniciar o pré-carregamento de anúncios

Para começar a pré-carregar anúncios, chame o método start uma vez ao inicializar GMA Next-Gen SDK. Depois que você chama o método start, o GMA Next-Gen SDK pré-carrega automaticamente os anúncios e tenta novamente as solicitações que falharam para as configurações pré-carregadas.

O exemplo a seguir mostra como iniciar o pré-carregamento de anúncios:

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Substitua AD_UNIT_ID pelo ID do seu bloco de anúncios.

O exemplo anterior mostra como usar o ID do bloco de anúncios como o ID de pré-carregamento. Um ID de pré-carregamento é um identificador de string que você cria para identificar uma configuração de pré-carregamento de anúncios. Se o app exigir várias configurações de segmentação para o mesmo ID de bloco de anúncios, transmita um identificador de string personalizado.

O pré-carregamento de anúncios não permite mudar os parâmetros de segmentação ou as solicitações de anúncios. Se você precisar mudar os parâmetros de segmentação entre as solicitações, use o carregamento único.

Receber e mostrar o anúncio pré-carregado

Antes de mostrar o anúncio, chame o método pollAd. Não armazene o objeto de anúncio pré-carregado. Quando você chama o método pollAd, o GMA Next-Gen SDK recupera um anúncio disponível e pré-carrega automaticamente o próximo anúncio em segundo plano. Se nenhum anúncio estiver disponível, GMA Next-Gen SDK não vai retornar anúncios.

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Quando o app chegar a uma posição do anúncio e puder chamar o método show, chame o método pollAd. Não chame o método pollAd em callbacks de pré-carregamento ou depois de verificar o método isAdAvailable para reter um anúncio. Se você precisar inspecionar os metadados do anúncio antes de mostrá-lo, leia as informações de resposta sem remover o anúncio do cache.

Detectar eventos de anúncio

Antes de veicular o anúncio, acompanhe os eventos de anúncio. O exemplo a seguir registra callbacks para eventos de anúncio:

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedAd
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        rewardedAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded ad failed to show.
        Log.e(TAG, "Rewarded ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded ad did record a click.
      }
    }
}

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedAd == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.");
    return;
  }

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded ad did dismiss.
          rewardedAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            FullScreenContentError fullScreenContentError) {
          // Rewarded ad failed to show.
          Log.e(TAG, "Rewarded ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded ad did record a click.
        }
      });
}

Opcional: validar callbacks de verificação do lado do servidor (SSV)

Para transmitir o contexto do usuário e do aplicativo em callbacks de verificação do lado do servidor (SSV), defina as opções de verificação no objeto de anúncio antes de mostrá-lo. Como os callbacks de SSV chegam ao seu servidor do Google sem estado de sessão, anexe as seguintes strings opcionais. O Google encaminha essas strings inalteradas como parâmetros de consulta assinados no callback de SSV.

• Parâmetro de consulta user_id: identifica o usuário que vai receber o crédito, como um ID da conta interna.
• Parâmetro de consulta custom_data: transporta dados do app, como o posicionamento da recompensa, o nível do jogo ou um valor de uso único gerado pelo servidor.

Se você não definir um valor, o Google vai omitir esse parâmetro de consulta do callback de SSV.

O exemplo a seguir define dados personalizados em um objeto de anúncio antes de mostrá-lo:

RewardedAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      rewardedAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedAd?.setServerSideVerificationOptions(options)
    }
  },
)

RewardedAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedAd ad) {
        rewardedAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedAd.setServerSideVerificationOptions(options);
      }
    });

Substitua SAMPLE_CUSTOM_DATA_STRING pelos seus dados personalizados.

Importante: o parâmetro de consulta custom_data é codificado por porcentagem. Antes de analisar o valor, decodifique o URL da string no servidor e verifique a assinatura de retorno de chamada antes de confiar nos parâmetros de consulta user_id ou custom_data.

Opcional: detectar eventos de pré-carregamento

Ao começar a pré-carregar anúncios, registre-se para receber eventos de pré-carregamento e ser notificado quando os anúncios forem pré-carregados, quando houver falha no pré-carregamento ou quando o cache de anúncios estiver esgotado.

O exemplo a seguir mostra como se registrar para eventos de pré-carregamento de anúncios:

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Quando um anúncio não é carregado, o GMA Next-Gen SDK pré-carrega anúncios automaticamente e tenta novamente as solicitações com falha para configurações pré-carregadas. Não invoque solicitações de carregamento manual em callbacks de falha. Nos métodos de callback de eventos de pré-carregamento, não chame os métodos pollAd, destroy ou start. Chamar esses métodos em callbacks pode invocar loops de carregamento recursivos.

Opcional: verificar a disponibilidade de anúncios

Se você precisar saber se um anúncio está disponível, verifique a disponibilidade dele. O exemplo a seguir verifica se um anúncio pré-carregado está disponível:

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedAdPreloader.isAdAvailable(adUnitId)
}

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.isAdAvailable(adUnitId);
}

Opcional: definir o tamanho do buffer

O tamanho do buffer controla o número de anúncios pré-carregados mantidos na memória. Por padrão, o Google otimiza o tamanho do buffer para equilibrar o consumo de memória e a latência de veiculação de anúncios. É possível definir um tamanho de buffer personalizado para aumentar ou diminuir o número de anúncios mantidos na memória. Recomendamos um tamanho de buffer de dois anúncios pré-carregados. Se a maior parte do tráfego vem de dispositivos com pouca memória, reduza o tamanho do buffer.

O exemplo a seguir mostra como definir um tamanho de buffer:

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
RewardedAdPreloader.start(adUnitId, preloadConfig);

Limites de cache de pré-carregamento

O GMA Next-Gen SDK aplica um limite em todo o app para o número total de anúncios pré-carregados em todos os blocos de anúncios e IDs de pré-carregamento:

• Limite padrão: o Google mantém no máximo seis anúncios pré-carregados na memória. Esse limite é compartilhado entre todos os formatos e IDs de pré-carregamento.
• Recomendamos manter um tamanho de buffer de dois para cada ID de pré-carregamento.

Opcional: interromper o pré-carregamento de anúncios

Mantenha o pré-carregamento ativo enquanto o app veicula anúncios. Durante esse período, não use o método destroy. Se você não precisar mostrar anúncios para um ID de pré-carregamento específico novamente na sessão, interrompa o pré-carregamento de anúncios. Para interromper o carregamento de anúncios de um ID de pré-carregamento específico, chame o método destroy com um ID de pré-carregamento. Chamar o método destroy remove do cache todos os anúncios pré-carregados associados ao ID de pré-carregamento.

O exemplo a seguir mostra como interromper o pré-carregamento de anúncios:

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId)
}

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId);
}

Opcional: leia as informações da resposta

Leia as informações de resposta do próximo anúncio pré-carregado sem remover o anúncio do cache. Se você precisar inspecionar os metadados do anúncio antes de mostrá-lo, leia as informações de resposta em vez de chamar o método pollAd.

O exemplo a seguir mostra como ler as informações da próxima resposta de anúncio pré-carregada:

val responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

ResponseInfo responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());