Anúncios de abertura do app

Selecione a plataforma: Android iOS Unity Flutter

Este guia é destinado a publishers que integram anúncios de abertura do app usando o SDK dos anúncios para dispositivos móveis do Google.

Os anúncios de abertura do app são um formato especial 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.

Esses anúncios mostram automaticamente uma pequena área de branding para que as pessoas saibam que estão no seu app. Esta é a aparência de um anúncio de abertura do app:

Pré-requisitos

Sempre use anúncios de teste

Ao criar e testar seus apps, use anúncios de teste em vez de anúncios de produção ativos. Sua conta poderá ser suspensa se isso não for feito.

A maneira mais fácil de carregar anúncios de teste é usar nosso ID de bloco de anúncios de teste dedicado para anúncios de abertura do app:

/21775744923/example/app-open

Ele foi configurado especialmente para retornar anúncios de teste em todas as solicitações, e você pode usá-lo nos seus próprios apps durante a programação, os testes e a depuração. Só não se esqueça de substituí-lo pelo ID do seu bloco de anúncios antes de publicar o app.

Para mais informações sobre como os anúncios de teste do SDK dos anúncios para dispositivos móveis do Google funcionam, consulte Ativar anúncios de teste.

Estender a classe Application

Crie uma classe que estenda a classe Application. Isso oferece uma maneira de gerenciar anúncios vinculados ao estado do aplicativo em vez de um único Activity:

Java

public class MyApplication extends Application
    implements ActivityLifecycleCallbacks, DefaultLifecycleObserver {

  private AppOpenAdManager appOpenAdManager;
  private Activity currentActivity;

  @Override
  public void onCreate() {
    super.onCreate();
    this.registerActivityLifecycleCallbacks(this);

    ProcessLifecycleOwner.get().getLifecycle().addObserver(this);
    appOpenAdManager = new AppOpenAdManager();
  }

MyApplication.java

Kotlin

class MyApplication :
  MultiDexApplication(), Application.ActivityLifecycleCallbacks, DefaultLifecycleObserver {

  private lateinit var appOpenAdManager: AppOpenAdManager
  private var currentActivity: Activity? = null

  override fun onCreate() {
    super<MultiDexApplication>.onCreate()
    registerActivityLifecycleCallbacks(this)

    ProcessLifecycleOwner.get().lifecycle.addObserver(this)
    appOpenAdManager = AppOpenAdManager()
  }

MyApplication.kt

Em seguida, adicione o seguinte código ao AndroidManifest.xml:

<!-- TODO: Update to reference your actual package name. -->
<application
    android:name="com.google.android.gms.example.appopendemo.MyApplication" ...>
...
</application>

Implementar o componente utilitário

Como o anúncio precisa aparecer rápido, é melhor carregá-lo com antecedência. Assim, você terá um anúncio pronto para ser veiculado quando o usuário entrar no app.

Implemente um componente utilitário AppOpenAdManager para encapsular o trabalho relacionado ao carregamento e à veiculação de anúncios de abertura do app:

Java

private class AppOpenAdManager {

  private static final String LOG_TAG = "AppOpenAdManager";
  private static final String AD_UNIT_ID = "/21775744923/example/app-open";

  private AppOpenAd appOpenAd = null;
  private boolean isLoadingAd = false;
  private boolean isShowingAd = false;

  /** Keep track of the time an app open ad is loaded to ensure you don't show an expired ad. */
  private long loadTime = 0;

  /** Constructor. */
  public AppOpenAdManager() {}
MyApplication.java

Kotlin

private inner class AppOpenAdManager {

  private val googleMobileAdsConsentManager =
  private var appOpenAd: AppOpenAd? = null
  private var isLoadingAd = false
  var isShowingAd = false

  /** Keep track of the time an app open ad is loaded to ensure you don't show an expired ad. */
  private var loadTime: Long = 0
MyApplication.kt

Para usar o AppOpenAdManager, chame os métodos de wrapper públicos na instância singleton MyApplication. A classe Application interage com o restante do código, delegando o trabalho de carregar e mostrar o anúncio ao gerenciador.

Carregar um anúncio

A próxima etapa é preencher o método loadAd() e processar os callbacks de carregamento de anúncios.

Java

AppOpenAd.load(
    context,
    "AD_UNIT_ID",
    new AdManagerAdRequest.Builder().build(),
    new AppOpenAdLoadCallback() {
      @Override
      public void onAdLoaded(AppOpenAd ad) {
        // Called when an app open ad has loaded.
        Log.d(LOG_TAG, "App open ad loaded.");

        appOpenAd = ad;
        isLoadingAd = false;
        loadTime = (new Date()).getTime();
      }

      @Override
      public void onAdFailedToLoad(LoadAdError loadAdError) {
        // Called when an app open ad has failed to load.
        Log.d(LOG_TAG, "App open ad failed to load with error: " + loadAdError.getMessage());

        isLoadingAd = false;
      }
    });
MyApplication.java

Kotlin

AppOpenAd.load(
  context,
  "AD_UNIT_ID",
  AdManagerAdRequest.Builder().build(),
  object : AppOpenAdLoadCallback() {
    override fun onAdLoaded(ad: AppOpenAd) {
      // Called when an app open ad has loaded.
      Log.d(LOG_TAG, "App open ad loaded.")

      appOpenAd = ad
      isLoadingAd = false
      loadTime = Date().time
    }

    override fun onAdFailedToLoad(loadAdError: LoadAdError) {
      // Called when an app open ad has failed to load.
      Log.d(LOG_TAG, "App open ad failed to load with error: " + loadAdError.message)

      isLoadingAd = false
    }
  },
)
MyApplication.kt

Substitua AD_UNIT_ID pelo ID do seu bloco de anúncios.

Mostrar o anúncio

A implementação mais comum de anúncios de abertura do app é tentar mostrar um anúncio perto do lançamento do app, iniciar o conteúdo do app se o anúncio não estiver pronto e pré-carregar outro anúncio para a próxima oportunidade de abertura do app. Confira orientações sobre anúncios de abertura do app para exemplos de implementação.

O código a seguir mostra e recarrega um anúncio:

Java

public void showAdIfAvailable(
    @NonNull final Activity activity,
    @NonNull OnShowAdCompleteListener onShowAdCompleteListener) {
  // If the app open ad is already showing, do not show the ad again.
  if (isShowingAd) {
    Log.d(TAG, "The app open ad is already showing.");
    return;
  }

  // If the app open ad is not available yet, invoke the callback then load the ad.
  if (appOpenAd == null) {
    Log.d(TAG, "The app open ad is not ready yet.");
    onShowAdCompleteListener.onShowAdComplete();
    // Load an ad.
    return;
  }

  isShowingAd = true;
  appOpenAd.show(activity);
}

AppOpenAdSnippets.java

Kotlin

fun showAdIfAvailable(activity: Activity, onShowAdCompleteListener: OnShowAdCompleteListener) {
  // If the app open ad is already showing, do not show the ad again.
  if (isShowingAd) {
    Log.d(TAG, "The app open ad is already showing.")
    return
  }

  // If the app open ad is not available yet, invoke the callback then load the ad.
  if (appOpenAd == null) {
    Log.d(TAG, "The app open ad is not ready yet.")
    onShowAdCompleteListener.onShowAdComplete()
    // Load an ad.
    return
  }

  isShowingAd = true
  appOpenAd?.show(activity)
}

AppOpenAdSnippets.kt

Definir o FullScreenContentCallback

O FullScreenContentCallback processa eventos relacionados à exibição do seu AppOpenAd. Antes de mostrar AppOpenAd, defina o callback:

Java

appOpenAd.setFullScreenContentCallback(
    new FullScreenContentCallback() {
      @Override
      public void onAdDismissedFullScreenContent() {
        // Called when full screen content is dismissed.
        Log.d(TAG, "Ad dismissed fullscreen content.");
        // Don't forget to set the ad reference to null so you
        // don't show the ad a second time.
        appOpenAd = null;
        isShowingAd = false;

        onShowAdCompleteListener.onShowAdComplete();
        // Load an ad.
      }

      @Override
      public void onAdFailedToShowFullScreenContent(@NonNull AdError adError) {
        // Called when full screen content failed to show.
        Log.d(TAG, adError.getMessage());
        appOpenAd = null;
        // Don't forget to set the ad reference to null so you
        // don't show the ad a second time.
        isShowingAd = false;

        onShowAdCompleteListener.onShowAdComplete();
        // Load an ad.
      }

      @Override
      public void onAdShowedFullScreenContent() {
        Log.d(TAG, "Ad showed fullscreen content.");
      }

      @Override
      public void onAdImpression() {
        // Called when an impression is recorded for an ad.
        Log.d(TAG, "The ad recorded an impression.");
      }

      @Override
      public void onAdClicked() {
        // Called when ad is clicked.
        Log.d(TAG, "The ad was clicked.");
      }
    });
AppOpenAdSnippets.java

Kotlin

appOpenAd?.fullScreenContentCallback =
  object : FullScreenContentCallback() {
    override fun onAdDismissedFullScreenContent() {
      // Called when full screen content is dismissed.
      Log.d(TAG, "Ad dismissed fullscreen content.")
      // Don't forget to set the ad reference to null so you
      // don't show the ad a second time.
      appOpenAd = null
      isShowingAd = false

      onShowAdCompleteListener.onShowAdComplete()
      // Load an ad.
    }

    override fun onAdFailedToShowFullScreenContent(adError: AdError) {
      // Called when full screen content failed to show.
      Log.d(TAG, adError.message)
      // Don't forget to set the ad reference to null so you
      // don't show the ad a second time.
      appOpenAd = null
      isShowingAd = false

      onShowAdCompleteListener.onShowAdComplete()
      // Load an ad.
    }

    override fun onAdShowedFullScreenContent() {
      Log.d(TAG, "Ad showed fullscreen content.")
    }

    override fun onAdImpression() {
      // Called when an impression is recorded for an ad.
      Log.d(TAG, "The ad recorded an impression.")
    }

    override fun onAdClicked() {
      // Called when ad is clicked.
      Log.d(TAG, "The ad was clicked.")
    }
  }
AppOpenAdSnippets.kt

Considerar a validade dos anúncios

Para não veicular uma publicidade expirada, adicione um método ao AppOpenAdManager que verifique o tempo decorrido desde que a referência foi carregada. Depois, use esse método para verificar se o anúncio ainda é válido.

Java

/** Check if ad was loaded more than n hours ago. */
private boolean wasLoadTimeLessThanNHoursAgo(long numHours) {
  long dateDifference = (new Date()).getTime() - loadTime;
  long numMilliSecondsPerHour = 3600000;
  return (dateDifference < (numMilliSecondsPerHour * numHours));
}

/** Check if ad exists and can be shown. */
private boolean isAdAvailable() {
  // For time interval details, see: https://support.google.com/admob/answer/9341964
  return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4);
}

MyApplication.java

Kotlin

/** Check if ad was loaded more than n hours ago. */
private fun wasLoadTimeLessThanNHoursAgo(numHours: Long): Boolean {
  val dateDifference: Long = Date().time - loadTime
  val numMilliSecondsPerHour: Long = 3600000
  return dateDifference < numMilliSecondsPerHour * numHours
}

/** Check if ad exists and can be shown. */
private fun isAdAvailable(): Boolean {
  // For time interval details, see: https://support.google.com/admob/answer/9341964
  return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4)
}

MyApplication.kt

Acompanhar a atividade atual

Para mostrar o anúncio, você precisa de um contexto de Activity. Para acompanhar a atividade mais atual em uso, registre-se e implemente o Application.ActivityLifecycleCallbacks.

Java

@Override
public void onActivityCreated(@NonNull Activity activity, @Nullable Bundle savedInstanceState) {}

@Override
public void onActivityStarted(@NonNull Activity activity) {
  // An ad activity is started when an ad is showing, which could be AdActivity class from Google
  // SDK or another activity class implemented by a third party mediation partner. Updating the
  // currentActivity only when an ad is not showing will ensure it is not an ad activity, but the
  // one that shows the ad.
  if (!appOpenAdManager.isShowingAd) {
    currentActivity = activity;
  }
}

@Override
public void onActivityResumed(@NonNull Activity activity) {}

@Override
public void onActivityPaused(@NonNull Activity activity) {}

@Override
public void onActivityStopped(@NonNull Activity activity) {}

@Override
public void onActivitySaveInstanceState(@NonNull Activity activity, @NonNull Bundle outState) {}

@Override
public void onActivityDestroyed(@NonNull Activity activity) {}

MyApplication.java

Kotlin

override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}

override fun onActivityStarted(activity: Activity) {
  // An ad activity is started when an ad is showing, which could be AdActivity class from Google
  // SDK or another activity class implemented by a third party mediation partner. Updating the
  // currentActivity only when an ad is not showing will ensure it is not an ad activity, but the
  // one that shows the ad.
  if (!appOpenAdManager.isShowingAd) {
    currentActivity = activity
  }
}

override fun onActivityResumed(activity: Activity) {}

override fun onActivityPaused(activity: Activity) {}

override fun onActivityStopped(activity: Activity) {}

override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) {}

override fun onActivityDestroyed(activity: Activity) {}

MyApplication.kt

registerActivityLifecycleCallbacks permite detectar todos os eventos Activity. Ao detectar quando as atividades são iniciadas e destruídas, você pode acompanhar uma referência ao Activity atual, que será usado para apresentar o anúncio de abertura do app.

Detectar eventos do app em primeiro plano

Para detectar eventos do app em primeiro plano, siga estas etapas:

Adicionar as bibliotecas ao arquivo gradle

Para receber notificações sobre eventos do app em primeiro plano, registre um DefaultLifecycleObserver. Adicione a dependência ao arquivo de build no nível do app:

Kotlin

  dependencies {
    implementation("com.google.android.gms:play-services-ads:24.5.0")
    implementation("androidx.lifecycle:lifecycle-process:2.8.3")
  }

Groovy

  dependencies {
    implementation 'com.google.android.gms:play-services-ads:24.5.0'
    implementation 'androidx.lifecycle:lifecycle-process:2.8.3'
  }

Implementar a interface do observador de ciclo de vida

Para detectar eventos de primeiro plano, implemente a interface DefaultLifecycleObserver.

Implemente o onStart() para mostrar o anúncio de abertura do app.

Java

@Override
public void onStart(@NonNull LifecycleOwner owner) {
  DefaultLifecycleObserver.super.onStart(owner);
  appOpenAdManager.showAdIfAvailable(currentActivity);
}

MyApplication.java

Kotlin

override fun onStart(owner: LifecycleOwner) {
  super.onStart(owner)
  currentActivity?.let {
    // Show the ad (if available) when the app moves to foreground.
    appOpenAdManager.showAdIfAvailable(it)
  }
}

MyApplication.kt

Inicializações a frio e telas de carregamento

Até agora, a documentação pressupõe que você só mostra anúncios de abertura do app no momento em que os usuários colocam o app em primeiro plano enquanto ele está suspenso na memória. As inicializações a frio ocorrem quando o app é iniciado, mas não estava suspenso na memória.

Um exemplo disso é quando um usuário abre seu app pela primeira vez. Com esse tipo de inicialização, não existe um anúncio de abertura do app carregado pronto para ser mostrado imediatamente. A demora entre a solicitação de um anúncio e o recebimento dele poderá criar uma situação em que os usuários conseguem usar seu app brevemente antes de serem surpreendidos por um anúncio fora de contexto. Evite essa experiência ruim do usuário.

A melhor maneira de usar anúncios de abertura do app em inicializações a frio é ter uma tela de carregamento para abrir os recursos do jogo ou app e mostrar o anúncio apenas nessa tela. Se o app terminar de carregar e direcionar o usuário para o conteúdo principal, não mostre o anúncio.

Práticas recomendadas

Os anúncios de abertura do app ajudam a gerar receita com a tela de carregamento quando o app é aberto pela primeira vez e durante a troca de apps. Mas é importante seguir as práticas recomendadas abaixo para que as pessoas gostem de usar seu app.

  • Mostre o primeiro anúncio de abertura do app depois que o usuário acessar o aplicativo algumas vezes.
  • Mostrar esses anúncios enquanto os usuários estão esperando o carregamento do app.
  • Se o carregamento da tela abaixo do anúncio de abertura do app terminar antes que o anúncio seja dispensado, convém dispensar essa tela no método onAdDismissedFullScreenContent().

Exemplos no GitHub

  • Exemplo de anúncios de abertura do app: Java | Kotlin

Próximas etapas

Confira os seguintes tópicos: