Configurare gli annunci apertura app

Seleziona la piattaforma: Android iOS Unity Flutter Android (legacy)

Gli annunci apertura app sono un formato dell'annuncio destinato ai publisher che vogliono monetizzare le schermate di caricamento delle loro app. I tuoi utenti possono chiudere gli annunci apertura app in qualsiasi momento. Quando gli utenti portano la tua app in primo piano, mostra gli annunci apertura app.

Per saperne di più, consulta le indicazioni per gli annunci apertura app.

Questa guida spiega come integrare gli annunci apertura app in un'app per Android.

Prima di iniziare

Prima di continuare, completa queste operazioni:

  • Configura GMA Next-Gen SDK.
  • Utilizza l'ID unità pubblicitaria apertura app di test ca-app-pub-3940256099942544/9257395921.
    • Durante la creazione e il test dell'app, assicurati di utilizzare annunci di prova anziché annunci di produzione pubblicati. Se non utilizzi l'ID unità pubblicitaria di test, Google può sospendere il tuo account.
    • Prima di pubblicare l'app, sostituisci questo ID con l'ID unità pubblicitaria.
    • Per informazioni dettagliate sugli annunci di prova GMA Next-Gen SDK, consulta Attiva gli annunci di prova.

Informazioni sul precaricamento degli annunci (beta)

Il precaricamento degli annunci in GMA Next-Gen SDK automatizza il caricamento e la memorizzazione nella cache degli annunci.

Il precaricamento degli annunci offre i seguenti vantaggi:

  • Gestione dei riferimenti: mantiene i riferimenti fino alla pubblicazione degli annunci.
  • Ricaricamento automatico: carica un nuovo annuncio quando ne viene recuperato uno dalla cache.
  • Nuovi tentativi gestiti: carica un nuovo annuncio quando non è possibile caricarne uno.
  • Gestione della scadenza: aggiorna gli annunci prima della scadenza.
  • Ottimizzazione della cache: ottimizza l'ordine della cache per pubblicare l'annuncio con la priorità più alta.

Avvia il precaricamento degli annunci

Per iniziare a precaricare gli annunci, chiama il metodo start una volta quando inizializzi GMA Next-Gen SDK. Dopo aver chiamato il metodo start, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova le richieste non riuscite per le configurazioni precaricate.

L'esempio seguente mostra come avviare il precaricamento degli annunci:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

Sostituisci AD_UNIT_ID con l'ID unità pubblicitaria.

L'esempio precedente mostra come utilizzare l'ID unità pubblicitaria come ID di precaricamento. Un ID di precaricamento è un identificatore di stringa che crei per identificare una configurazione di precaricamento degli annunci. Se la tua app richiede più configurazioni di targeting per lo stesso ID unità pubblicitaria, trasmetti un identificatore di stringa personalizzato.

Il precaricamento degli annunci non supporta la modifica dei parametri di targeting o delle richieste di annunci. Se devi modificare i parametri di targeting tra una richiesta e l'altra, utilizza il caricamento singolo.

Recupera e mostra l'annuncio precaricato

Prima di mostrare l'annuncio, chiama il metodo pollAd. Non memorizzare l'oggetto dell'annuncio precaricato. Quando chiami il metodo pollAd, GMA Next-Gen SDK recupera un annuncio disponibile e precarica automaticamente l'annuncio successivo in background. Se non è disponibile alcun annuncio, GMA Next-Gen SDK non restituisce annunci.

Quando hai un oggetto annuncio disponibile, chiama il metodo show per visualizzare l'annuncio. L'esempio seguente mostra come recuperare e mostrare un annuncio precaricato:

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);
}

Quando la tua app raggiunge un posizionamento dell'annuncio e può chiamare il metodo show, chiama il metodo pollAd. Non chiamare il metodo pollAd nei callback di precaricamento o dopo aver controllato il metodo isAdAvailable per trattenere un annuncio. Se devi esaminare i metadati dell'annuncio prima di mostrarlo, leggi le informazioni sulla risposta senza rimuovere l'annuncio dalla cache.

Ascolta gli eventi degli annunci

Prima di mostrare l'annuncio, ascolta gli eventi dell'annuncio. L'esempio seguente registra i callback per gli eventi degli annunci:

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.
        }
      });
}

(Facoltativo) Ascolta gli eventi di precaricamento

Quando inizi a precaricare gli annunci, registrati agli eventi precaricati per ricevere una notifica quando gli annunci vengono precaricati correttamente, non vengono precaricati o la cache degli annunci è esaurita.

L'esempio seguente mostra come registrarsi per il precaricamento degli eventi degli annunci:

Kotlin

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

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 un annuncio non viene caricato, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova le richieste non andate a buon fine per le configurazioni precaricate. Non richiamare richieste di caricamento manuale nei callback di errore. Nei metodi di callback degli eventi precaricati, non chiamare i metodi pollAd, destroy o start. La chiamata di questi metodi nei callback può richiamare loop di caricamento ricorsivi.

(Facoltativo) Verifica la disponibilità degli annunci

Se hai bisogno di sapere se un annuncio è disponibile, controlla la disponibilità degli annunci. L'esempio seguente verifica se è disponibile un annuncio precaricato:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return AppOpenAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return AppOpenAdPreloader.isAdAvailable(adUnitId);
}

(Facoltativo) Imposta la dimensione del buffer

La dimensione del buffer controlla il numero di annunci precaricati conservati in memoria. Per impostazione predefinita, Google ottimizza la dimensione del buffer per bilanciare il consumo di memoria e la latenza di pubblicazione degli annunci. Puoi impostare una dimensione del buffer personalizzata per aumentare o diminuire il numero di annunci conservati in memoria. Ti consigliamo una dimensione del buffer di due annunci precaricati. Se la maggior parte del traffico proviene da dispositivi con memoria ridotta, riduci la dimensione del buffer.

L'esempio seguente mostra come impostare una dimensione del buffer:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

Limiti della cache di precaricamento

GMA Next-Gen SDK applica un limite a livello di app al numero totale di annunci precaricati in tutte le unità pubblicitarie e gli ID di precaricamento:

  • Limite predefinito: Google conserva in memoria un massimo di sei annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID di precaricamento.
  • Ti consigliamo di mantenere una dimensione del buffer pari a due per ogni ID di precaricamento.

(Facoltativo) Interrompi il precaricamento degli annunci

Mantieni attivo il precaricamento mentre la tua app pubblica annunci. Durante questo periodo, non utilizzare il metodo destroy. Se non hai bisogno di mostrare nuovamente gli annunci per un ID di precaricamento specifico nella sessione, puoi interrompere il precaricamento degli annunci. Per interrompere il caricamento degli annunci per un ID di precaricamento specifico, chiama il metodo destroy con un ID di precaricamento. La chiamata al metodo destroy rimuove dalla cache tutti gli annunci precaricati associati all'ID di precaricamento.

L'esempio seguente mostra come interrompere il precaricamento degli annunci:

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);
}

(Facoltativo) Leggi le informazioni sulla risposta

Leggi le informazioni sulla risposta dell'annuncio precaricato successivo senza rimuovere l'annuncio dalla cache. Se devi ispezionare i metadati degli annunci prima di mostrarli, leggi le informazioni sulla risposta anziché chiamare il metodo pollAd.

L'esempio seguente mostra come leggere le informazioni sulla risposta all'annuncio precaricato successivo:

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());

Gestisci gli avvii a freddo e le schermate di caricamento

Un avvio a freddo si verifica quando l'app viene avviata dal disco, mentre un avvio a caldo si verifica quando riapri l'app dalla memoria. Durante un avvio a freddo, non hai un annuncio precaricato da mostrare immediatamente. Durante un avvio a caldo, potresti avere ancora un annuncio precaricato pronto per essere mostrato.

Durante un avvio a freddo, gli utenti potrebbero interagire con l'app prima che venga caricata e mostri un annuncio. Per evitare un'esperienza utente negativa, mostra gli annunci apertura app durante gli avvii a freddo esclusivamente da una schermata di caricamento mentre vengono caricati gli asset dell'app. Se il caricamento degli asset viene completato e l'utente raggiunge i contenuti principali prima del caricamento dell'annuncio, non mostrare l'annuncio.

Consigli

Segui questi consigli per gli annunci apertura app:

  • Non mostrare un annuncio apertura app al primo avvio dell'app.
  • Se la schermata di caricamento termina il caricamento mentre l'annuncio è visualizzato, ignorala nel metodo di callback per la chiusura dell'annuncio.
  • Gli annunci apertura app scadono quattro ore dopo il caricamento. Non mostrare un annuncio apertura app che è stato caricato da più di quattro ore.