Este guia é destinado aos editores que integram os anúncios de abertura do app usando a API SDK de anúncios para dispositivos móveis.
Os anúncios de abertura do app são um formato de anúncio especial destinado a editores que querem gerar receita as telas de carregamento do app. Os anúncios de abertura do app podem ser fechados a qualquer momento e foram criados seja exibido quando os usuários levarem seu app para o primeiro plano.
Os anúncios de abertura do app mostram automaticamente uma pequena área de branding para os usuários saberem que estão neles seu app. Confira um exemplo de anúncio de abertura do app:
Pré-requisitos
- Leia o Guia explicativo.
Sempre faça testes com 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 é usando nosso ID de bloco de anúncios de teste dedicado para apps. abrir anúncios:
ca-app-pub-3940256099942544/9257395921
Ele foi configurado especialmente para retornar anúncios de teste para todas as solicitações, e você sem custos para usá-lo nos seus próprios apps durante a programação, o teste e a depuração. Apenas faça lembre-se de substituí-lo pelo seu próprio ID do bloco de anúncios antes de publicar o aplicativo.
Para mais informações sobre como funcionam os anúncios de teste do SDK dos anúncios para dispositivos móveis do Google, consulte Ative os anúncios de teste.
Estender a classe Application
Crie uma nova classe que estenda a Application
e adicione o seguinte
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ê registrará mais tarde 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 deve ser exibido rapidamente, por isso é melhor carregá-lo antes de precisar exibi-la. Dessa forma, você terá um anúncio pronto para exibição assim que o usuário acessar no seu app.
Implemente um componente utilitário AppOpenAdManager
para fazer solicitações de anúncios antes das
quando você precisa exibir 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 de utilitário, pode instanciá-la no seu
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 o carregamento do anúncio.
.
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;
}
})
}
// ...
}
Exiba o anúncio e processe eventos de callback em tela cheia
A implementação mais comum de abertura do app é tentar mostrar um anúncio de abertura do app próximo à inicialização 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. Consulte Orientações sobre anúncios de abertura do app para conferir exemplos de implementação.
O código a seguir demonstra como exibir e atualizar 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)
}
// ...
}
}
A
FullScreenContentCallback
lida com eventos como quando o anúncio é apresentado, não é apresentado ou é
dispensada.
Considerar a validade dos anúncios
Para garantir que você não exiba um anúncio expirado, adicione um método ao AppOpenAdManager
que verifica quanto tempo se passou desde o carregamento da referência de anúncio. Então, use isso
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)
}
}
Monitorar a atividade atual
Para mostrar o anúncio, você precisa de um contexto Activity
. Para acompanhar
atividade atual em uso, registre-se e implemente a
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 que você detecte todos os eventos Activity
. Ouvindo quando as atividades
sejam iniciados e destruídos, você pode acompanhar uma referência à atual
Activity
, que você vai usar para apresentar seu 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.3.0") implementation("androidx.lifecycle:lifecycle-process:2.8.3") }
Groovy
dependencies { implementation 'com.google.android.gms:play-services-ads:23.3.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 o
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ó exibe anúncios de abertura do app quando os usuários seu app em primeiro plano quando ele está suspenso na memória. "Inicializações a frio" ocorrem quando o app for iniciado, mas não tiver sido suspenso na memória.
Um exemplo de inicialização a frio é quando um usuário abre o app pela primeira vez. Com inicializações a frio, você não terá um anúncio de abertura do app carregado anteriormente pronto para ser exibidos imediatamente. É o atraso entre a solicitação e o recebimento de um anúncio pode criar uma situação em que os usuários podem usar o app brevemente antes ser surpreendido por um anúncio fora de contexto. Isso deve ser evitado, porque é uma uma experiência ruim do usuário.
A maneira preferencial de usar anúncios de abertura do app em inicializações a frio é uma tela de carregamento para carregar seu jogo ou recursos do app e só mostrar o anúncio do tela. Se o app tiver concluído o carregamento e enviado o usuário para a página principal não exiba 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 é exibido pela primeira vez inicializações e durante trocas de aplicativos, mas é importante manter as práticas recomendadas para que os usuários aproveitem seu app. É melhor fazer o seguinte:
- Exiba o primeiro anúncio de abertura do app depois que os usuários tiverem usado o aplicativo algumas vezes.
- Veicule anúncios de abertura do app nos momentos em que os usuários estariam esperando para o app carregar.
- Se você tem uma tela de carregamento abaixo do anúncio de abertura do app e sua tela de carregamento
concluir o carregamento antes de o anúncio ser dispensado, você pode querer
tela de carregamento no método
onAdDismissedFullScreenContent()
.
Exemplos no GitHub
Próximas etapas
Confira os seguintes tópicos: