Questa guida è destinata ai publisher che integrano gli annunci di apertura dell'app utilizzando l'SDK Google Mobile Ads (beta).
Gli annunci apertura app sono un formato pubblicitario speciale destinato ai publisher che vogliono monetizzare le schermate di caricamento delle loro app. Gli annunci apertura app possono essere chiusi in qualsiasi momento e sono progettati per essere mostrati quando gli utenti portano la tua app in primo piano.
Gli annunci apertura app mostrano automaticamente una piccola area di branding, in modo che gli utenti sappiano di essere all'interno della tua app. Ecco un esempio di annuncio apertura app:
Prerequisiti
- Completa la Guida introduttiva.
Esegui sempre i test con gli annunci di prova
Quando crei e testi le tue app, assicurati di utilizzare annunci di prova anziché annunci di produzione live. In caso contrario, il tuo account potrebbe essere sospeso.
Il modo più semplice per caricare gli annunci di test è utilizzare il nostro ID unità pubblicitaria di test dedicato per gli annunci all'apertura dell'app:
ca-app-pub-3940256099942544/9257395921
È stato configurato appositamente per restituire annunci di test per ogni richiesta e puoi utilizzarlo liberamente nelle tue app durante la codifica, i test e il debug. Assicurati solo di sostituirlo con il tuo ID unità pubblicitaria prima di pubblicare l'app.
Per ulteriori informazioni sul funzionamento degli annunci di test dell'SDK Google Mobile Ads (beta), consulta la pagina Attivare gli annunci di test.
Estendi la classe Application
Crea una nuova classe che estenda la classe Application
. In questo modo, puoi gestire gli annunci associati allo stato dell'applicazione in modo consapevole del ciclo di vita anziché con un singolo Activity
:
Kotlin
/** Application class that initializes, loads and show ads when activities change states. */
class MyApplication : Application() {
override fun onCreate() {
super<Application>.onCreate()
CoroutineScope(Dispatchers.IO).launch {
// Initialize the Mobile Ads SDK synchronously on a background thread.
MobileAds.initialize(this@MyApplication, InitializationConfig.Builder(APP_ID).build()) {}
}
}
private companion object {
// Sample AdMob App ID.
const val APP_ID = "ca-app-pub-3940256099942544~3347511713"
}
}
Java
/** Application class that initializes, loads and show ads when activities change states. */
public class MyApplication extends Application {
// Sample AdMob App ID.
private static final String APP_ID = "ca-app-pub-3940256099942544~3347511713";
@Override
public void onCreate() {
super.onCreate();
new Thread(
() -> {
// Initialize the SDK on a background thread.
MobileAds.initialize(
MyApplication.this,
new InitializationConfig.Builder(APP_ID).build(),
initializationStatus -> {});
})
.start();
}
}
Fornisce lo scheletro in cui in seguito ti registrerai per gli eventi di primo piano dell'app.
Successivamente, aggiungi il seguente codice a AndroidManifest.xml
:
<!-- TODO: Update to reference your actual package name. -->
<application
android:name="com.google.android.gms.example.appopendemo.MyApplication" ...>
...
</application>
Implementa il componente di utilità
L'annuncio deve essere visualizzato rapidamente, quindi è meglio caricarlo prima di doverlo mostrare. In questo modo, avrai un annuncio pronto non appena l'utente entra nella tua app.
Implementa un componente di utilità AppOpenAdManager
per incapsulare il lavoro relativo
al caricamento e alla visualizzazione degli annunci per l'apertura dell'app:
Kotlin
/**
* Interface definition for a callback to be invoked when an app open ad is complete (i.e. dismissed
* or fails to show).
*/
fun interface OnShowAdCompleteListener {
fun onShowAdComplete()
}
/** Singleton object that loads and shows app open ads. */
object AppOpenAdManager {
private var appOpenAd: AppOpenAd? = null
private var isLoadingAd = false
var isShowingAd = false
/**
* Load an ad.
*
* @param context a context used to perform UI-related operations (e.g. display Toast messages).
* Showing the app open ad itself does not require a context.
*/
fun loadAd(context: Context) {
// We will implement this later.
}
/**
* Show the ad if one isn't already showing.
*
* @param activity the activity that shows the app open ad.
* @param onShowAdCompleteListener the listener to be notified when an app open ad is complete.
*/
fun showAdIfAvailable(activity: Activity, onShowAdCompleteListener: OnShowAdCompleteListener?) {
// We will implement this later.
}
/** Check if ad exists and can be shown. */
private fun isAdAvailable(): Boolean {
return appOpenAd != null
}
}
Java
/** Singleton object that loads and shows app open ads. */
public class AppOpenAdManager {
/**
* Interface definition for a callback to be invoked when an app open ad is complete (i.e.
* dismissed or fails to show).
*/
public interface OnShowAdCompleteListener {
void onShowAdComplete();
}
private static AppOpenAdManager instance;
private AppOpenAd appOpenAd;
private boolean isLoadingAd = false;
private boolean isShowingAd = false;
/** Keep track of the time an app open ad is loaded to make sure you don't show an expired ad. */
private long loadTime = 0;
public static synchronized AppOpenAdManager getInstance() {
if (instance == null) {
instance = new AppOpenAdManager();
}
return instance;
}
/**
* Load an ad.
*
* @param context a context used to perform UI-related operations (e.g. display Toast messages).
* Loading the app open ad itself does not require a context.
*/
public void loadAd(@NonNull Context context) {
// We will implement this later.
}
/**
* Show the ad if one isn't already showing.
*
* @param activity the activity that shows the app open ad.
* @param onShowAdCompleteListener the listener to be notified when an app open ad is complete.
*/
public void showAdIfAvailable(
@NonNull Activity activity, @Nullable OnShowAdCompleteListener onShowAdCompleteListener) {
// We will implement this later.
}
/** Check if ad exists and can be shown. */
private boolean isAdAvailable() {
return appOpenAd != null
}
}
Ora che hai una classe di utilità, puoi istanziarla nella classe
MyApplication
:
Java
public class MyApplication extends Application {
private AppOpenAdManager appOpenAdManager;
@Override
public void onCreate() {
super.onCreate();
new Thread(
() -> {
// Initialize Google Mobile Ads SDK (beta) 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 Google Mobile Ads SDK (beta) on a background thread.
MobileAds.initialize(this@MyApplication) {}
}
appOpenAdManager = AppOpenAdManager()
}
}
Per utilizzare AppOpenAdManager
, chiama i metodi wrapper pubblici sul singleton
MyApplication
. L'interfaccia della classe Application
interagisce con il resto del codice, delegando al gestore il compito di caricare e mostrare l'annuncio.
Caricare un annuncio
Il passaggio successivo consiste nel compilare il metodo loadAd()
e gestire i callback di caricamento degli annunci.
Kotlin
/**
* Load an ad.
*
* @param context a context used to perform UI-related operations (e.g. display Toast messages).
* Loading the app open ad itself does not require a context.
*/
fun loadAd(context: Context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
Log.d(Constant.TAG, "App open ad is either loading or has already loaded.")
return
}
isLoadingAd = true
AppOpenAd.load(
AdRequest.Builder(AppOpenFragment.AD_UNIT_ID).build(),
object : AdLoadCallback<AppOpenAd> {
/**
* Called when an app open ad has loaded.
*
* @param ad the loaded app open ad.
*/
override fun onAdLoaded(ad: AppOpenAd) {
// Called when an ad has loaded.
appOpenAd = ad
isLoadingAd = false
Log.d(Constant.TAG, "App open ad loaded.")
}
/**
* Called when an app open ad has failed to load.
*
* @param loadAdError the error.
*/
override fun onAdFailedToLoad(loadAdError: LoadAdError) {
isLoadingAd = false
Log.w(Constant.TAG, "App open ad failed to load: $loadAdError")
}
},
)
}
Java
/**
* Load an ad.
*
* @param context a context used to perform UI-related operations (e.g. display Toast messages).
* Loading the app open ad itself does not require a context.
*/
public void loadAd(@NonNull Context context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
Log.d(Constant.TAG, "App open ad is either loading or has already loaded.");
return;
}
isLoadingAd = true;
AppOpenAd.load(
new AdRequest.Builder(AppOpenFragment.AD_UNIT_ID).build(),
new AdLoadCallback<AppOpenAd>() {
@Override
public void onAdLoaded(@NonNull AppOpenAd ad) {
appOpenAd = ad;
isLoadingAd = false;
Log.d(Constant.TAG, "App open ad loaded.");
}
@Override
public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) {
isLoadingAd = false;
Log.w(Constant.TAG, "App open ad failed to load: " + loadAdError);
}
});
}
Sostituisci AD_UNIT_ID con il tuo ID unità pubblicitaria.
Mostra l'annuncio
L'implementazione più comune dell'annuncio apertura app consiste nel tentare di mostrare un annuncio apertura app vicino all'avvio dell'app, avviare i contenuti dell'app se l'annuncio non è pronto e precaricare un altro annuncio per la successiva opportunità di apertura dell'app. Consulta Indicazioni per gli annunci apertura app per esempi di implementazione.
Il seguente codice mostra e ricarica successivamente un annuncio:
Kotlin
/**
* Show the ad if one isn't already showing.
*
* @param activity the activity that shows the app open ad.
* @param onShowAdCompleteListener the listener to be notified when an app open ad is complete.
*/
fun showAdIfAvailable(activity: Activity, onShowAdCompleteListener: OnShowAdCompleteListener?) {
// If the app open ad is already showing, do not show the ad again.
if (isShowingAd) {
Log.d(Constant.TAG, "App open ad is already showing.")
onShowAdCompleteListener?.onShowAdComplete()
return
}
// If the app open ad is not available yet, invoke the callback.
if (!isAdAvailable()) {
Log.d(Constant.TAG, "App open ad is not ready yet.")
onShowAdCompleteListener?.onShowAdComplete()
return
}
appOpenAd?.adEventCallback =
object : AppOpenAdEventCallback {
override fun onAdShowedFullScreenContent() {
Log.d(Constant.TAG, "App open ad showed.")
}
override fun onAdDismissedFullScreenContent() {
Log.d(Constant.TAG, "App open ad dismissed.")
appOpenAd = null
isShowingAd = false
onShowAdCompleteListener?.onShowAdComplete()
loadAd(activity)
}
override fun onAdFailedToShowFullScreenContent(
fullScreenContentError: FullScreenContentError
) {
appOpenAd = null
isShowingAd = false
Log.w(Constant.TAG, "App open ad failed to show: $fullScreenContentError")
onShowAdCompleteListener?.onShowAdComplete()
loadAd(activity)
}
override fun onAdImpression() {
Log.d(Constant.TAG, "App open ad recorded an impression.")
}
override fun onAdClicked() {
Log.d(Constant.TAG, "App open ad recorded a click.")
}
}
isShowingAd = true
appOpenAd?.show(activity)
}
Java
/**
* Show the ad if one isn't already showing.
*
* @param activity the activity that shows the app open ad.
* @param onShowAdCompleteListener the listener to be notified when an app open ad is complete.
*/
public void showAdIfAvailable(
@NonNull Activity activity, @Nullable OnShowAdCompleteListener onShowAdCompleteListener) {
// If the app open ad is already showing, do not show the ad again.
if (isShowingAd) {
Log.d(Constant.TAG, "App open ad is already showing.");
if (onShowAdCompleteListener != null) {
onShowAdCompleteListener.onShowAdComplete();
}
return;
}
// If the app open ad is not available yet, invoke the callback.
if (!isAdAvailable()) {
Log.d(Constant.TAG, "App open ad is not ready yet.");
if (onShowAdCompleteListener != null) {
onShowAdCompleteListener.onShowAdComplete();
}
return;
}
appOpenAd.setAdEventCallback(
new AppOpenAdEventCallback() {
@Override
public void onAdShowedFullScreenContent() {
Log.d(Constant.TAG, "App open ad shown.");
}
@Override
public void onAdDismissedFullScreenContent() {
Log.d(Constant.TAG, "App open ad dismissed.");
appOpenAd = null;
isShowingAd = false;
if (onShowAdCompleteListener != null) {
onShowAdCompleteListener.onShowAdComplete();
}
loadAd(activity);
}
@Override
public void onAdFailedToShowFullScreenContent(
@NonNull FullScreenContentError fullScreenContentError) {
appOpenAd = null;
isShowingAd = false;
Log.w(Constant.TAG, "App open ad failed to show: " + fullScreenContentError);
if (onShowAdCompleteListener != null) {
onShowAdCompleteListener.onShowAdComplete();
}
loadAd(activity);
}
@Override
public void onAdImpression() {
Log.d(Constant.TAG, "App open ad recorded an impression.");
}
@Override
public void onAdClicked() {
Log.d(Constant.TAG, "App open ad recorded a click.");
}
});
isShowingAd = true;
appOpenAd.show(activity);
}
AppOpenAdEventCallback
gestisce eventi come la presentazione dell'annuncio, la mancata presentazione o la chiusura.
Considera la scadenza degli annunci
Per assicurarti di non mostrare un annuncio scaduto, aggiungi un metodo a AppOpenAdManager
che controlla il tempo trascorso dal caricamento del riferimento dell'annuncio. Quindi, utilizza questo
metodo per verificare se l'annuncio è ancora valido.
Kotlin
object AppOpenAdManager {
// ...
/** Keep track of the time an app open ad is loaded to make sure you don't show an expired ad. */
private var loadTime: Long = 0;
/**
* Load an ad.
*
* @param context a context used to perform UI-related operations (e.g. display Toast messages).
* Loading the app open ad itself does not require a context.
*/
fun loadAd(context: Context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
Log.d(Constant.TAG, "App open ad is either loading or has already loaded.")
return
}
isLoadingAd = true
AppOpenAd.load(
AdRequest.Builder(AppOpenFragment.AD_UNIT_ID).build(),
object : AdLoadCallback<AppOpenAd> {
/**
* Called when an app open ad has loaded.
*
* @param ad the loaded app open ad.
*/
override fun onAdLoaded(ad: AppOpenAd) {
// Called when an ad has loaded.
appOpenAd = ad
isLoadingAd = false
loadTime = Date().time
Log.d(Constant.TAG, "App open ad loaded.")
}
/**
* Called when an app open ad has failed to load.
*
* @param loadAdError the error.
*/
override fun onAdFailedToLoad(loadAdError: LoadAdError) {
isLoadingAd = false
Log.w(Constant.TAG, "App open ad failed to load: $loadAdError")
}
},
)
}
// ...
/** 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 {
// App open ads expire after four hours. Ads rendered more than four hours after request time
// are no longer valid and may not earn revenue.
return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4)
}
}
Java
public class AppOpenAdManager {
// ...
/** Keep track of the time an app open ad is loaded to make sure you don't show an expired ad. */
private long loadTime = 0;
/**
* Load an ad.
*
* @param context a context used to perform UI-related operations (e.g. display Toast messages).
* Loading the app open ad itself does not require a context.
*/
public void loadAd(@NonNull Context context) {
// Do not load ad if there is an unused ad or one is already loading.
if (isLoadingAd || isAdAvailable()) {
Log.d(Constant.TAG, "App open ad is either loading or has already loaded.");
return;
}
isLoadingAd = true;
AppOpenAd.load(
new AdRequest.Builder(AppOpenFragment.AD_UNIT_ID).build(),
new AdLoadCallback<AppOpenAd>() {
@Override
public void onAdLoaded(@NonNull AppOpenAd ad) {
appOpenAd = ad;
isLoadingAd = false;
loadTime = new Date().getTime();
Log.d(Constant.TAG, "App open ad loaded.");
}
@Override
public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) {
isLoadingAd = false;
Log.w(Constant.TAG, "App open ad failed to load: " + loadAdError);
}
});
}
// ...
/** Check if ad was loaded more than n hours ago. */
private boolean wasLoadTimeLessThanNHoursAgo(long numHours) {
long dateDifference = new Date().getTime() - loadTime;
long numMilliSecondsPerHour = 3600000L;
return dateDifference < numMilliSecondsPerHour * numHours;
}
/** Check if ad exists and can be shown. */
private boolean isAdAvailable() {
// App open ads expire after four hours. Ads rendered more than four hours after request time
// are no longer valid and may not earn revenue.
return appOpenAd != null && wasLoadTimeLessThanNHoursAgo(4);
}
}
Monitorare l'attività corrente
Per mostrare l'annuncio, devi avere un contesto Activity
. Per tenere traccia dell'attività più
recente in uso, registrati e implementa
Application.ActivityLifecycleCallbacks
.
Kotlin
class MyApplication : Application(), Application.ActivityLifecycleCallbacks {
private var currentActivity: Activity? = null
override fun onCreate() {
super<Application>.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) {}
// ...
}
Java
public class MyApplication extends Application
implements Application.ActivityLifecycleCallbacks {
private Activity currentActivity;
@Override
public void onCreate() {
super.onCreate();
registerActivityLifecycleCallbacks(this);
}
/** ActivityLifecycleCallback methods. */
@Override
public void onActivityCreated(@NonNull Activity activity, @Nullable Bundle bundle) {}
@Override
public void onActivityStarted(@NonNull Activity activity) {
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 bundle) {}
@Override
public void onActivityDestroyed(@NonNull Activity activity) {}
// ...
}
registerActivityLifecycleCallbacks
ti consente di ascoltare tutti gli eventi Activity
. Ascoltando quando le attività
vengono avviate e distrutte, puoi tenere traccia di un riferimento all'Activity
corrente, che utilizzerai per mostrare l'annuncio di apertura dell'app.
Ascolta gli eventi di messa in primo piano dell'app
Per rilevare gli eventi in primo piano dell'app:
Aggiungi le librerie al file Gradle
Per ricevere notifiche sugli eventi di primo piano dell'app, devi registrare un
DefaultLifecycleObserver
. Aggiungi la dipendenza al file di build a livello di app:
Kotlin
dependencies { implementation("com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:0.21.0-beta01") implementation("androidx.lifecycle:lifecycle-process:2.8.3") }
Trendy
dependencies { implementation 'com.google.android.libraries.ads.mobile.sdk:ads-mobile-sdk:0.21.0-beta01' implementation 'androidx.lifecycle:lifecycle-process:2.8.3' }
Implementa l'interfaccia dell'osservatore del ciclo di vita
Puoi rilevare gli eventi di primo piano implementando l'interfaccia
DefaultLifecycleObserver
.
Implementa onStart()
per mostrare l'annuncio apertura app.
Kotlin
class MyApplication :
Application(), Application.ActivityLifecycleCallbacks, DefaultLifecycleObserver {
private var currentActivity: Activity? = null
override fun onCreate() {
super<Application>.onCreate()
registerActivityLifecycleCallbacks(this)
ProcessLifecycleOwner.get().lifecycle.addObserver(this)
}
/**
* DefaultLifecycleObserver method that shows the app open ad when the app moves to foreground.
*/
override fun onStart(owner: LifecycleOwner) {
currentActivity?.let { activity ->
AppOpenAdManager.showAdIfAvailable(activity, null)
}
}
// ...
}
Java
public class MyApplication extends Application
implements Application.ActivityLifecycleCallbacks, DefaultLifecycleObserver {
private Activity currentActivity;
@Override
public void onCreate() {
super.onCreate();
registerActivityLifecycleCallbacks(this);
ProcessLifecycleOwner.get().getLifecycle().addObserver(this);
}
/**
* DefaultLifecycleObserver method that shows the app open ad when the app moves to foreground.
*/
@Override
public void onStart(@NonNull LifecycleOwner owner) {
if (currentActivity == null) {
return;
}
AppOpenAdManager.getInstance().showAdIfAvailable(currentActivity, null);
}
// ...
}
Avvii a freddo e schermate di caricamento
La documentazione finora presuppone che tu mostri gli annunci apertura app solo quando gli utenti portano in primo piano la tua app quando è sospesa in memoria. Gli "avvii completi" si verificano quando la tua app viene avviata, ma non era stata sospesa in precedenza in memoria.
Un esempio di avvio completo è quando un utente apre la tua app per la prima volta. Con gli avvii completi, non avrai un annuncio apertura app caricato in precedenza e pronto per essere mostrato immediatamente. Il ritardo tra il momento in cui richiedi un annuncio e il momento in cui lo ricevi può creare una situazione in cui gli utenti possono utilizzare brevemente la tua app prima di essere sorpresi da un annuncio fuori contesto. Questo comportamento deve essere evitato perché peggiora l'esperienza utente.
Il modo migliore per utilizzare gli annunci apertura app negli avvii a freddo è utilizzare una schermata di caricamento per caricare gli asset del gioco o dell'app e mostrare l'annuncio solo dalla schermata di caricamento. Se il caricamento dell'app è stato completato e l'utente è stato indirizzato ai contenuti principali dell'app, non mostrare l'annuncio.
Best practice
Gli annunci apertura app ti aiutano a monetizzare la schermata di caricamento della tua app, al primo avvio dell'app e durante il cambio di app, ma è importante tenere a mente le best practice per consentire agli utenti di utilizzare la tua app. È consigliabile:
- Mostra l'annuncio di prima apertura dell'app dopo che gli utenti l'hanno utilizzata alcune volte.
- Mostra gli annunci apertura app nei momenti in cui gli utenti altrimenti dovrebbero aspettare che la tua app si carichi.
- Se hai una schermata di caricamento sotto l'annuncio apertura app e il caricamento
viene completato prima che l'annuncio venga chiuso, ti consigliamo di chiudere la
schermata di caricamento nel metodo
onAdDismissedFullScreenContent()
.
Esempio
Scarica ed esegui l'app di esempio che mostra l'utilizzo dell'SDK Google Mobile Ads (beta).