Configurare gli annunci apertura app

l'SDK Vertex AI Pipelines.

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

Gli annunci apertura app sono un formato di annunci 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.

Per saperne di più, consulta le linee guida 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 prova ca-app-pub-3940256099942544/9257395921.
    • Quando crei e testi la tua app, assicurati di utilizzare annunci di prova anziché annunci live di produzione. Se non utilizzi l'ID unità pubblicitaria di prova, Google può sospendere il tuo account.
    • Prima di pubblicare l'app, sostituisci questo ID con l'ID unità pubblicitaria.
    • Per i dettagli sugli annunci di prova GMA Next-Gen SDK, consulta la sezione Attivare gli annunci di prova.

Informazioni sul precaricamento degli annunci

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 visualizzazione degli annunci.
  • Ricaricamento automatico: carica un nuovo annuncio quando ne viene recuperato uno dalla cache.
  • Ripetizioni gestite: carica un nuovo annuncio quando il caricamento di uno non riesce.
  • 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.

Avviare il precaricamento degli annunci

Per iniziare a precaricare gli annunci, chiama il metodo startPreload() una volta all'avvio dell'app. Dopo aver chiamato il metodo startPreload(), GMA Next-Gen SDK precarica automaticamente gli annunci e riprova a inviare le richieste non riuscite per le configurazioni precaricate.

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

Kotlin

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  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 creato da te per identificare una configurazione di precaricamento degli annunci. Se la tua app richiede più configurazioni di targeting per lo stesso ID unità pubblicitaria, passa un identificatore di stringa personalizzato.

Recuperare e mostrare l'annuncio precaricato

Quando vuoi mostrare un annuncio, chiama 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 ne restituisce.

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

Evita di chiamare il metodo pollAd() finché non sei pronto a mostrare un annuncio. Per leggere le informazioni sulla risposta dell'annuncio senza mostrarlo, consulta la sezione Leggere le informazioni sulla risposta.

Ascoltare gli eventi degli annunci

Prima di mostrare l'annuncio, ascolta gli eventi degli annunci. L'esempio seguente mostra come registrare 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) Ascoltare gli eventi di precaricamento

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

L'esempio seguente mostra come registrarsi per ricevere gli eventi di precaricamento degli annunci:

Kotlin

private fun startPreloadingWithCallback(adUnitId: String) {
  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

private void startPreloadingWithCallback(String adUnitId) {
  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 il caricamento di un annuncio non riesce, GMA Next-Gen SDK precarica automaticamente gli annunci e riprova a inviare le richieste non riuscite per le configurazioni precaricate.

(Facoltativo) Verificare la disponibilità degli annunci

Se devi sapere se un annuncio è disponibile, verifica la disponibilità degli annunci. L'esempio seguente mostra come verificare 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) Impostare la dimensione del buffer

La dimensione del buffer controlla il numero di annunci precaricati mantenuti in memoria. Per impostazione predefinita, Google ottimizza la dimensione del buffer per bilanciare il consumo di memoria e la latenza della pubblicazione degli annunci. Puoi impostare una dimensione del buffer personalizzata per aumentare il numero di annunci mantenuti in memoria. Ti consigliamo di impostare una dimensione massima del buffer di quattro.

L'esempio seguente mostra come impostare una dimensione del buffer di quattro annunci precaricati:

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Four is the recommended maximum buffer size.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
  AppOpenAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Four is the recommended maximum buffer size.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
  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 mantiene in memoria un massimo di 6 annunci precaricati. Questo limite è condiviso tra tutti i formati e gli ID di precaricamento.
  • Ti consigliamo di mantenere una dimensione del buffer di 2 o 3 per ID di precaricamento.

(Facoltativo) Interrompere il precaricamento degli annunci

Se non devi mostrare di nuovo 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) Leggere le informazioni sulla risposta

Leggi le informazioni sulla risposta del prossimo annuncio precaricato senza rimuovere l'annuncio dalla cache.

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

Avvii a freddo e schermate di caricamento

Un avvio a freddo si verifica quando l'app viene avviata da zero, ad esempio quando un utente apre l'app per la prima volta o dopo la terminazione della memoria. Durante un avvio a freddo, non hai un annuncio apertura app caricato in precedenza pronto per essere mostrato immediatamente.

A causa dei ritardi nelle richieste di annunci, gli utenti potrebbero interagire con la tua app prima che venga visualizzato un annuncio apertura app. Per evitare un'esperienza utente scadente, mostra gli annunci apertura app durante gli avvii a freddo rigorosamente da una schermata di caricamento mentre gli asset dell'app vengono caricati. Se il caricamento degli asset viene completato e l'utente raggiunge i contenuti principali prima del caricamento dell'annuncio, non mostrare l'annuncio.

Carica gli asset dell'app su un thread in background in modo che il caricamento continui mentre l'annuncio viene visualizzato.

Best practice

Segui queste best practice per gli annunci apertura app:

  • Mostra il primo annuncio apertura app solo dopo che un utente ha aperto l'app più volte.
  • Mostra gli annunci apertura app solo mentre gli utenti attendono il caricamento dell'app.
  • Se la schermata di caricamento termina il caricamento mentre l'annuncio viene visualizzato, chiudi la schermata di caricamento nel metodo di callback dell'annuncio chiuso.