Configurar anúncios de abertura do app

SDK.

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

Os anúncios de abertura do app são um formato destinado a publishers que querem gerar receita com as telas de carregamento do app. Eles podem ser fechados a qualquer momento e são projetados para aparecer quando os usuários colocam seu app em primeiro plano.

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

Este guia explica como integrar anúncios de abertura do app 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 de abertura do app de teste ca-app-pub-3940256099942544/9257395921.
    • 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 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 do 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

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  AppOpenAdPreloader.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 = 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);
}

Evite chamar o método pollAd() até que você esteja 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

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 iniciar o pré-carregamento de anúncios, registre-se para eventos de pré-carregamento para receber uma notificação 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

private fun startPreloadingWithCallback(adUnitId: String) {
  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

private void startPreloadingWithCallback(String adUnitId) {
  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 um anúncio falha ao carregar, 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 de anúncios. O exemplo a seguir mostra como verificar 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. 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

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Four is the recommended maximum buffer size.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Four is the recommended maximum buffer size.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
  AppOpenAdPreloader.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.
  AppOpenAdPreloader.destroy(adUnitId)
}

Java

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

Inicializações a frio e telas de carregamento

Uma inicialização a frio ocorre quando o app é iniciado do zero, por exemplo, quando um usuário abre o app pela primeira vez ou após o encerramento da memória. Durante uma inicialização a frio, você não tem um anúncio de abertura do app carregado anteriormente pronto para ser mostrado imediatamente.

Devido a atrasos na solicitação de anúncios, os usuários podem interagir com seu app antes que um anúncio de abertura do app apareça. Para evitar uma experiência ruim do usuário, mostre 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 de recursos for concluído e o usuário chegar ao conteúdo principal antes que o anúncio seja carregado, não mostre o anúncio.

Carregue os recursos do app em uma linha de execução em segundo plano para que o carregamento continue enquanto o anúncio é mostrado.

Práticas recomendadas

Siga estas práticas recomendadas para anúncios de abertura do app:

  • Mostre o primeiro anúncio de abertura do app somente depois que um usuário abrir o app várias vezes.
  • Mostre anúncios de abertura do app somente enquanto os usuários aguardam o carregamento do app.
  • Se a tela de carregamento terminar de carregar enquanto o anúncio estiver sendo mostrado, dispense a tela de carregamento no método de callback do anúncio dispensado.