Configurar anúncios de abertura do app

Os anúncios de abertura do app são um formato destinado a publishers que querem gerar receita com as telas de carregamento. Os usuários podem fechar esses anúncios a qualquer momento. Quando eles deixarem seu aplicativo em primeiro plano, veicule anúncios de abertura do app.

Para mais informações, consulte as orientações sobre anúncios de abertura do app.

Neste guia, explicamos como integrar anúncios de abertura do app a um aplicativo 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 de teste de abertura do app ca-app-pub-3940256099942544/9257395921.
    • Ao criar e testar seu app, use anúncios de teste em vez de anúncios de produção reais. 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 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 no GMA Next-Gen SDK automatiza o carregamento e o armazenamento em cache de anúncios.

Ele proporciona os seguintes benefícios:

  • Gerenciamento de referências: mantém as referências até que os anúncios sejam veiculados.
  • Recarregamento automático: carrega um novo anúncio quando um é recuperado do cache.
  • Tentativas gerenciadas: carrega um novo anúncio quando um falha.
  • Tratamento de expiração: atualiza os anúncios antes que eles expirem.
  • 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 start uma vez ao inicializar o 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 fazer de novo 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

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

Java

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

Substitua AD_UNIT_ID pelo seu ID do 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 nem 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 veicular o anúncio pré-carregado

Antes de veicular 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 em segundo plano. Se nenhum anúncio estiver disponível, o 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 veicular o anúncio. O exemplo a seguir mostra como recuperar e veicular 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 = AppOpenAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "App open ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "App open 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.
  AppOpenAd ad = AppOpenAdPreloader.pollAd(adUnitId);

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

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

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

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

Detectar eventos de anúncios

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

Kotlin

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

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

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

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

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

Java

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

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

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

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

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

Opcional: detectar eventos de pré-carregamento

Ao começar a pré-carregar anúncios, registre-se para eventos de pré-carregamento e receba notificações quando os anúncios forem pré-carregados, o pré-carregamento apresentar falha 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 =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "App open preload ad $preloadId failed to load with error: ${adError.message}")
    }

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

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

Java

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

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, String.format("App open preload ad %s is not available", preloadId));
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, String.format("App open preload ad %s is available", preloadId));
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Quando o carregamento de um anúncio falha, o GMA Next-Gen SDK pré-carrega anúncios automaticamente e tenta fazer de novo as solicitações que falharam para as configurações pré-carregadas. Não invoque solicitações de carregamento manual em callbacks de falha. Nos métodos de callback dos eventos de pré-carregamento, não chame pollAd, destroy nem 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 AppOpenAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return AppOpenAdPreloader.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 vier de dispositivos com pouca memória, reduza o tamanho do buffer.

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

Kotlin

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

Java

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);
AppOpenAdPreloader.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 igual a 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. Quando quiser 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 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.
  AppOpenAdPreloader.destroy(adUnitId)
}

Java

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

Opcional: ler as informações da resposta

Leia as informações da 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 veiculá-lo, leia as informações da 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 = AppOpenAdPreloader.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 = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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

Lidar com inicializações a frio e telas de carregamento

Uma inicialização a frio ocorre quando o app é iniciado pelo disco, e uma inicialização com estado salvo ocorre quando você reabre o app da memória. Durante uma inicialização a frio, você não tem um anúncio pré-carregado para veicular imediatamente. Durante uma inicialização com estado salvo, talvez você ainda tenha um anúncio pré-carregado pronto para veicular.

Na inicialização a frio, os usuários podem interagir com o app antes que ele carregue e veicule um anúncio. Para evitar que eles tenham uma experiência ruim, veicule anúncios de abertura do app em inicializações a frio estritamente em uma tela de carregamento enquanto os recursos do app são carregados. Se o carregamento dos recursos for concluído e o usuário chegar ao conteúdo principal antes que o carregamento do anúncio termine, não veicule o anúncio.

Recomendações

Siga estas recomendações para anúncios de abertura do app:

  • Não mostre um anúncio de abertura do app na primeira inicialização.
  • Se a tela terminar o carregamento enquanto o anúncio é veiculado, dispense-a no método de callback de encerramento do anúncio.
  • Os anúncios de abertura do app expiram quatro horas após o carregamento. Não mostre um anúncio de abertura do app que foi carregado há mais de quatro horas.