Este guia é destinado a editores que estão integrando anúncios de abertura de 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 editores que querem gerar receita com as telas de carregamento do app. Os anúncios de abertura do app podem ser fechados a qualquer momento e são projetados para aparecer quando os usuários trazem o app para o primeiro plano.
Os anúncios de abertura do app mostram automaticamente uma pequena área de branding para que os usuários saibam que estão no seu app. Confira um exemplo de anúncio de abertura do app:
Pré-requisitos
- Leia o Guia explicativo.
Sempre teste com anúncios de teste
Ao criar e testar seus apps, use anúncios de teste em vez de publicidade de produção ativa. Sua conta poderá ser suspensa se isso não for feito.
A maneira mais fácil de carregar anúncios de teste é usar o ID dedicado do bloco de anúncios de teste para anúncios abertos do app:
ca-app-pub-3940256099942544/9257395921
Ele foi configurado especialmente para retornar anúncios de teste para cada solicitação, e você pode usá-lo nos seus próprios apps durante a programação, o teste e a depuração. Só não se esqueça de substituí-lo pelo seu ID de 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 nova classe que estenda a Application
e adicione o seguinte código para inicializar o SDK dos anúncios para dispositivos móveis do Google quando seu app for iniciado.
Java
/** Application class that initializes, loads and show ads when activities change states. */
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
})
.start();
}
}
Kotlin
/** Application class that initializes, loads and show ads when activities change states. */
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
}
}
Isso inicializa o SDK e fornece o esqueleto em que você vai se registrar para eventos em primeiro plano do app.
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 seu componente utilitário
Seu anúncio precisa ser mostrado rapidamente. Por isso, é melhor fazer o carregamento antes de exibi-lo. Dessa forma, você terá um anúncio pronto assim que o usuário entrar no app.
Implemente um componente utilitário AppOpenAdManager
para fazer solicitações de anúncio antes
de mostrar o anúncio.
Java
public class MyApplication extends Application {
// ...
/** Inner class that loads and shows app open ads. */
private class AppOpenAdManager {
private static final String LOG_TAG = "AppOpenAdManager";
private static final String AD_UNIT_ID = "ca-app-pub-3940256099942544/9257395921";
private AppOpenAd appOpenAd = null;
private boolean isLoadingAd = false;
private boolean isShowingAd = false;
/** Constructor. */
public AppOpenAdManager() {}
/** Request an ad. */
private void loadAd(Context context) {
// We will implement this later.
}
/** Check if ad exists and can be shown. */
private boolean isAdAvailable() {
return appOpenAd != null;
}
}
}
Kotlin
private const val String LOG_TAG = "AppOpenAdManager"
private const val String AD_UNIT_ID = "ca-app-pub-3940256099942544/9257395921"
public class MyApplication extends Application {
// ...
/** Inner class that loads and shows app open ads. */
private inner class AppOpenAdManager {
private var appOpenAd: AppOpenAd? = null
private var isLoadingAd = false
var isShowingAd = false
/** Request an ad. */
fun loadAd(context: Context) {
// We will implement this later.
}
/** Check if ad exists and can be shown. */
private fun isAdAvailable(): Boolean {
return appOpenAd != null
}
}
}
Agora que você tem uma classe utilitária, é possível instanciar essa classe na
classe MyApplication
:
Java
public class MyApplication extends Application {
private AppOpenAdManager appOpenAdManager;
@Override
public void onCreate() {
super.onCreate();
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
})
.start();
appOpenAdManager = new AppOpenAdManager(this);
}
}
Kotlin
class MyApplication : Application() {
private lateinit var appOpenAdManager: AppOpenAdManager
override fun onCreate() {
super.onCreate()
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
appOpenAdManager = AppOpenAdManager()
}
}
Carregar um anúncio
A próxima etapa é preencher o método loadAd()
e processar os callbacks de carregamento
de anúncios.
Java
private class AppOpenAdManager {
// ...
/** Request an ad. */
public void loadAd(Context context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
return;
}
isLoadingAd = true;
AdRequest request = new AdRequest.Builder().build();
AppOpenAd.load(
context, AD_UNIT_ID, request,
AppOpenAd.APP_OPEN_AD_ORIENTATION_PORTRAIT,
new AppOpenAdLoadCallback() {
@Override
public void onAdLoaded(AppOpenAd ad) {
// Called when an app open ad has loaded.
Log.d(LOG_TAG, "Ad was 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, loadAdError.getMessage());
isLoadingAd = false;
}
});
}
// ...
}
Kotlin
private inner class AppOpenAdManager {
// ...
/** Request an ad. */
fun loadAd(context: Context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
return
}
isLoadingAd = true
val request = AdRequest.Builder().build()
AppOpenAd.load(
context, AD_UNIT_ID, request,
AppOpenAd.APP_OPEN_AD_ORIENTATION_PORTRAIT,
object : AppOpenAdLoadCallback() {
override fun onAdLoaded(ad: AppOpenAd) {
// Called when an app open ad has loaded.
Log.d(LOG_TAG, "Ad was 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, loadAdError.message)
isLoadingAd = false;
}
})
}
// ...
}
Mostrar o anúncio e processar eventos de callback em tela cheia
A implementação mais comum é tentar mostrar um anúncio de abertura do app perto do lançamento, 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. Consulte as orientações sobre anúncios de abertura do app para ver exemplos de implementação.
O código a seguir demonstra como mostrar e recarregar um anúncio:
Java
public class MyApplication extends Application {
// ...
/** Interface definition for a callback to be invoked when an app open ad is complete. */
public interface OnShowAdCompleteListener {
void onShowAdComplete();
}
private class AppOpenAdManager {
// ...
/** Shows the ad if one isn't already showing. */
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(LOG_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 (!isAdAvailable()) {
Log.d(LOG_TAG, "The app open ad is not ready yet.");
onShowAdCompleteListener.onShowAdComplete();
loadAd(activity);
return;
}
appOpenAd.setFullScreenContentCallback(
new FullScreenContentCallback() {
@Override
public void onAdDismissedFullScreenContent() {
// Called when fullscreen content is dismissed.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, "Ad dismissed fullscreen content.");
appOpenAd = null;
isShowingAd = false;
onShowAdCompleteListener.onShowAdComplete();
loadAd(activity);
}
@Override
public void onAdFailedToShowFullScreenContent(AdError adError) {
// Called when fullscreen content failed to show.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, adError.getMessage());
appOpenAd = null;
isShowingAd = false;
onShowAdCompleteListener.onShowAdComplete();
loadAd(activity);
}
@Override
public void onAdShowedFullScreenContent() {
// Called when fullscreen content is shown.
Log.d(LOG_TAG, "Ad showed fullscreen content.");
}
});
isShowingAd = true;
appOpenAd.show(activity);
}
// ...
}
}
Kotlin
class MyApplication : Application() {
// ...
/** Interface definition for a callback to be invoked when an app open ad is complete. */
interface OnShowAdCompleteListener {
fun onShowAdComplete()
}
private inner class AppOpenAdManager {
// ...
/** Shows the ad if one isn't already showing. */
fun showAdIfAvailable(
activity: Activity,
onShowAdCompleteListener: OnShowAdCompleteListener) {
// If the app open ad is already showing, do not show the ad again.
if (isShowingAd) {
Log.d(LOG_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 (!isAdAvailable()) {
Log.d(LOG_TAG, "The app open ad is not ready yet.")
onShowAdCompleteListener.onShowAdComplete()
loadAd(activity)
return
}
appOpenAd?.setFullScreenContentCallback(
object : FullScreenContentCallback() {
override fun onAdDismissedFullScreenContent() {
// Called when full screen content is dismissed.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, "Ad dismissed fullscreen content.")
appOpenAd = null
isShowingAd = false
onShowAdCompleteListener.onShowAdComplete()
loadAd(activity)
}
override fun onAdFailedToShowFullScreenContent(adError: AdError) {
// Called when fullscreen content failed to show.
// Set the reference to null so isAdAvailable() returns false.
Log.d(LOG_TAG, adError.message)
appOpenAd = null
isShowingAd = false
onShowAdCompleteListener.onShowAdComplete()
loadAd(activity)
}
override fun onAdShowedFullScreenContent() {
// Called when fullscreen content is shown.
Log.d(LOG_TAG, "Ad showed fullscreen content.")
}
})
isShowingAd = true
appOpenAd?.show(activity)
}
// ...
}
}
O
FullScreenContentCallback
processa eventos, como quando o anúncio é apresentado, falha na apresentação ou é
encerrado.
Considerar a validade dos anúncios
Para garantir que você não mostre um anúncio expirado, adicione um método ao AppOpenAdManager
que verifique quanto tempo passou desde o carregamento da referência de anúncio. Em seguida, use esse
método para verificar se o anúncio ainda é válido.
Java
private class AppOpenAdManager {
// ...
/** Keep track of the time an app open ad is loaded to ensure you don't show an expired ad. */
private long loadTime = 0;
// ...
/** Utility method to check if ad was loaded more than n hours ago. */
private boolean wasLoadTimeLessThanNHoursAgo(long numHours) {
long dateDifference = (new Date()).getTime() - this.loadTime;
long numMilliSecondsPerHour = 3600000;
return (dateDifference < (numMilliSecondsPerHour * numHours));
}
/** Check if ad exists and can be shown. */
public boolean isAdAvailable() {
return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4);
}
}
Kotlin
private inner class AppOpenAdManager {
// ...
/** 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;
// ...
/** Utility method to 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 {
return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4)
}
}
Acompanhar a atividade atual
Para mostrar o anúncio, você precisa de um contexto Activity
. Para acompanhar a atividade
mais recente que está sendo usada, registre e implemente o
Application.ActivityLifecycleCallbacks
.
Java
public class MyApplication extends Application implements ActivityLifecycleCallbacks {
private Activity currentActivity;
@Override
public void onCreate() {
super.onCreate();
this.registerActivityLifecycleCallbacks(this);
// ...
}
/** ActivityLifecycleCallback methods. */
@Override
public void onActivityCreated(Activity activity, Bundle savedInstanceState) {}
@Override
public void onActivityStarted(Activity activity) {
currentActivity = activity
}
@Override
public void onActivityResumed(Activity activity) {}
@Override
public void onActivityStopped(Activity activity) {}
@Override
public void onActivityPaused(Activity activity) {}
@Override
public void onActivitySaveInstanceState(Activity activity, Bundle bundle) {}
@Override
public void onActivityDestroyed(Activity activity) {}
}
Kotlin
class MyApplication : Application(), Application.ActivityLifecycleCallbacks {
private var currentActivity: Activity? = null
override fun onCreate() {
super.onCreate()
registerActivityLifecycleCallbacks(this)
// ...
}
/** ActivityLifecycleCallback methods. */
override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {}
override fun onActivityStarted(activity: Activity) {
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) {}
}
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 em primeiro plano do app
Adicionar as bibliotecas ao arquivo do Gradle
Para receber notificações sobre eventos em primeiro plano do app, registre um
DefaultLifecycleObserver
. Adicione a dependência dele ao arquivo de build no nível do app:
Kotlin
dependencies { implementation("com.google.android.gms:play-services-ads:23.5.0") implementation("androidx.lifecycle:lifecycle-process:2.8.3") }
Groovy
dependencies { implementation 'com.google.android.gms:play-services-ads:23.5.0' implementation 'androidx.lifecycle:lifecycle-process:2.8.3' }
Implementar a interface do observador do ciclo de vida
Para detectar eventos em primeiro plano, implemente a
interface DefaultLifecycleObserver
.
Implemente o evento onStart
para mostrar o anúncio de abertura do app.
Java
public class MyApplication extends Application
implements ActivityLifecycleCallbacks, LifecycleObserver {
// ...
@Override
public void onCreate() {
super.onCreate();
this.registerActivityLifecycleCallbacks(this);
new Thread(
() -> {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this, initializationStatus -> {});
})
.start();
ProcessLifecycleOwner.get().getLifecycle().addObserver(this);
appOpenAdManager = new AppOpenAdManager();
}
/** LifecycleObserver method that shows the app open ad when the app moves to foreground. */
@OnLifecycleEvent(Event.ON_START)
protected void onMoveToForeground() {
// Show the ad (if available) when the app moves to foreground.
appOpenAdManager.showAdIfAvailable(currentActivity);
}
/** Show the ad if one isn't already showing. */
private void showAdIfAvailable(@NonNull final Activity activity) {
showAdIfAvailable(
activity,
new OnShowAdCompleteListener() {
@Override
public void onShowAdComplete() {
// Empty because the user will go back to the activity that shows the ad.
}
});
}
}
Kotlin
class MyApplication : Application(),
Application.ActivityLifecycleCallbacks, LifecycleObserver {
// ...
override fun onCreate() {
super.onCreate()
registerActivityLifecycleCallbacks(this)
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
// Initialize the Google Mobile Ads SDK on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
ProcessLifecycleOwner.get().lifecycle.addObserver(this)
appOpenAdManager = AppOpenAdManager()
}
/** LifecycleObserver method that shows the app open ad when the app moves to foreground. */
@OnLifecycleEvent(Lifecycle.Event.ON_START)
fun onMoveToForeground() {
// Show the ad (if available) when the app moves to foreground.
currentActivity?.let {
appOpenAdManager.showAdIfAvailable(it)
}
}
/** Show the ad if one isn't already showing. */
fun showAdIfAvailable(activity: Activity) {
showAdIfAvailable(
activity,
object : OnShowAdCompleteListener {
override fun onShowAdComplete() {
// Empty because the user will go back to the activity that shows the ad.
}
})
}
}
Telas de carregamento e inicializações a frio
A documentação até agora pressupõe que você só exibirá anúncios de abertura do app quando os usuários primeiro colocarem seu app em primeiro plano quando ele estiver suspenso na memória. As "inicializações a frio" ocorrem quando o app é iniciado, mas não foi suspenso anteriormente na memória.
Um exemplo de inicialização a frio é quando um usuário abre seu app pela primeira vez. Com as inicializações a frio, você não terá um anúncio de abertura de app carregado anteriormente que esteja pronto para ser mostrado imediatamente. O atraso entre o momento em que você solicita um anúncio e o momento em que ele é recebido pode criar uma situação em que os usuários podem usar seu app brevemente antes de se surpreenderem com um anúncio fora do contexto. Isso precisa ser evitado, porque é uma experiência ruim para o usuário.
A maneira preferencial de usar anúncios de abertura do app em inicializações a frio é usar uma tela de carregamento para carregar os recursos do app ou jogo e mostrar o anúncio somente nessa tela. Se o carregamento do app for concluído e o usuário for enviado ao conteúdo principal do app, não mostre o anúncio.
Práticas recomendadas
Os anúncios de abertura do app ajudam a gerar receita na tela de carregamento do seu app, quando ele é iniciado pela primeira vez e durante a troca dele. No entanto, é importante seguir as práticas recomendadas para que os usuários aproveitem seu app. É melhor:
- Mostre o primeiro anúncio de abertura do app depois que o usuário acessar o aplicativo algumas vezes.
- Exiba anúncios de abertura do app quando os usuários estiverem 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
Próximas etapas
Confira os seguintes tópicos: