Configurar anúncios intersticiais

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

Os anúncios intersticiais são anúncios em tela cheia que cobrem a interface do app. Você exibe esses anúncios em pontos de transição naturais no seu app, como entre atividades ou durante pausas nos níveis do jogo.

Quando um anúncio intersticial aparece no app, os usuários podem tocar nele e continuar ou fechar e voltar para o app. Leia este estudo de caso.

Neste guia, explicamos como integrar anúncios intersticiais 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 de teste ca-app-pub-3940256099942544/1033173712.
    • 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 (Beta) no GMA Next-Gen SDK automatiza o carregamento e o armazenamento em cache de anúncios.

A pré-carga de anúncios oferece os seguintes benefícios:

  • Gerenciamento de referências: mantém as referências até que os anúncios sejam mostrados.
  • Recarga automática: carrega um novo anúncio quando um é recuperado do cache.
  • Repetições 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 do cache: otimiza a ordem do cache para veicular o anúncio de maior prioridade.
Observação: para carregar anúncios manualmente, consulte Carregar um único anúncio intersticial.

Iniciar o pré-carregamento de anúncios

Para começar a pré-carregar anúncios, chame o método startPreload() uma vez no início do app. Depois de chamar o método startPreload(), GMA Next-Gen SDK pré-carrega automaticamente os anúncios e tenta novamente as solicitações com falha para configurações pré-carregadas.

O exemplo a seguir mostra como começar a pré-carregar 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)
  InterstitialAdPreloader.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);
  InterstitialAdPreloader.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 ID de pré-carga. Um ID de pré-carregamento de anúncios é 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.

Receber e mostrar o anúncio pré-carregado

Quando quiser mostrar um anúncio, chame 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 nada.

Quando você tiver um objeto de anúncio disponível, chame o método show para mostrar o anúncio. O exemplo a seguir mostra como recuperar e exibir 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 = InterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

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

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

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

  // Show the ad.
  ad.show(activity);
}

Até que você esteja pronto para mostrar um anúncio, evite chamar o método pollAd(). Para ler as informações da resposta do anúncio sem mostrá-las, consulte Ler as informações da resposta.

Detectar eventos de anúncios

Antes de mostrar o anúncio, detecte eventos de anúncio. O exemplo a seguir registra callbacks para eventos de anúncio:

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

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

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

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

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

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

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

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

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

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

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

Opcional: detectar eventos de pré-carregamento

Ao começar a fazer o pré-carregamento de anúncios, registre-se para receber notificações sobre eventos de pré-carregamento quando os anúncios forem pré-carregados com sucesso, não forem pré-carregados ou o cache de anúncios estiver esgotado.

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

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,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "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, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.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(
                "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, "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, "Interstitial preload ad " + preloadId + " is available");
      }
    };

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

Quando um anúncio não é carregado, o GMA Next-Gen SDK faz o pré-carregamento automático de anúncios e tenta novamente solicitações com falha para configurações pré-carregadas.

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 InterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.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 da veiculação de anúncios. Você pode definir um tamanho de buffer personalizado para aumentar o número de anúncios mantidos na memória. Recomendamos um tamanho de buffer de dois anúncios pré-carregados.

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)
  InterstitialAdPreloader.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);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Limites de cache de pré-carga

O GMA Next-Gen SDK impõe 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 um máximo de seis anúncios pré-carregados na memória. Esse limite é compartilhado entre todos os formatos e IDs de pré-carga.
  • Recomendamos manter um tamanho de buffer de dois para cada ID de pré-carga.

Opcional: interromper a pré-carga de anúncios

Se você não precisar mostrar anúncios para um ID de pré-carga específico novamente na sessão, é possível interromper a pré-carga. Para interromper o carregamento de anúncios para um ID de pré-carregamento específico, chame o método destroy() com um ID de pré-carregamento. Chamar o método destroy() remove todos os anúncios pré-carregados associados ao ID de pré-carga do cache.

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.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

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

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

Kotlin

val responseInfo = InterstitialAdPreloader.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 = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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