Configurar anúncios intersticiais

Selecionar plataforma: Android iOS Unity Flutter Android (legado)

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

Quando um anúncio intersticial aparece no app, o usuário pode tocar nele e continuar ou fechar o anúncio e voltar para o app. Leia um dos nossos estudos 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 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 mais detalhes sobre os anúncios de teste GMA Next-Gen SDK, consulte Ativar anúncios de teste.

Entender o pré-carregamento de anúncios

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.
  • Repetições gerenciadas: carrega um novo anúncio quando um falha ao carregar.
  • Processamento de expiração: atualiza os anúncios antes de expirar.
  • Otimização de cache: otimiza a ordem do cache para veicular 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 startPreload() uma vez na inicialização do app. Depois de chamar o método startPreload(), GMA Next-Gen SDK pré-carrega anúncios automaticamente e repete as solicitações com falha para configurações pré-carregadas.

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

Kotlin

// 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

// 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 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 do 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(). 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 retornará anúncios.

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 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 = 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);
}

Evite chamar o método pollAd() até que esteja tudo pronto para mostrar um anúncio. Para ler as informações de resposta do anúncio sem mostrá-lo, consulte Ler as informações de resposta.

Detectar eventos de anúncios

Antes de mostrar o anúncio, detecte eventos de anúncios. O exemplo a seguir mostra como registrar callbacks para eventos de anúncios:

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 iniciar o pré-carregamento de anúncios, registre-se para receber notificações quando os anúncios forem pré-carregados com sucesso, falharem ao pré-carregar ou 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,
        ("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, GMA Next-Gen SDK pré-carrega anúncios automaticamente e repete 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 mostra como verificar 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 de 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 máximo de buffer de quatro.

O exemplo a seguir mostra como definir um tamanho de buffer de quatro anúncios pré-carregados:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

Limites de cache de pré-carregamento

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 um máximo de seis anúncios pré-carregados na memória. Esse limite é compartilhado em todos os formatos e IDs de pré-carregamento.
  • Recomendamos manter um tamanho de buffer de 2 ou 3 por ID de pré-carregamento.

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

Se você não precisar mostrar anúncios para um ID de pré-carregamento específico novamente na sessão, poderá interromper o pré-carregamento de anúncios. 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é-carregamento 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: ler as informações de 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 informações de resposta do próximo 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());