Configurar anúncios intersticiais premiados

Selecione a plataforma: Android iOS Unity Flutter Android (legada)

Os anúncios intersticiais premiados são um formato que permite oferecer recompensas em anúncios que aparecem automaticamente durante transições naturais do app. Diferente dos anúncios premiados, os usuários não precisam ativar a visualização dos intersticiais premiados. Para mais informações, consulte as orientações sobre intersticiais premiados.

Neste guia, explicamos como integrar anúncios intersticiais 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 intersticiais premiados de teste ca-app-pub-3940256099942544/5354046379.
    • 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:

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  RewardedInterstitialAdPreloader.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.

Quando você tiver um objeto de anúncio disponível, chame o método show para mostrar o anúncio. Use um listener de recompensa para processar eventos premiados. O exemplo a seguir mostra como recuperar e mostrar um anúncio pré-carregado:

Kotlin

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

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

Java

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

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

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial 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:

Kotlin

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

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

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

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

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

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

Java

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

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

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

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

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

        @Override
        public void onAdClicked() {
          // Rewarded interstitial 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:

Kotlin

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

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.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:

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

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

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.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:

Kotlin

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

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.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:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  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);
  RewardedInterstitialAdPreloader.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:

Kotlin

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

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.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:

Kotlin

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

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

Java

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

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