Configurer des annonces interstitielles

Sélectionnez une plate-forme : Android iOS Unity Flutter Android (Legacy)

Les annonces interstitielles sont des annonces plein écran qui recouvrent l'interface de l'application. Vous diffusez ces annonces à des moments de transition naturels dans votre application, par exemple entre deux activités ou pendant les pauses entre les niveaux de jeu.

Lorsque votre application affiche une annonce interstitielle, vos utilisateurs peuvent appuyer dessus et continuer, ou la fermer et revenir à l'application.

Ce guide explique comment intégrer des annonces interstitielles dans une application Android.

Avant de commencer

Avant de continuer, procédez comme suit :

  • Configurer GMA Next-Gen SDK
  • Utilisez l'ID du bloc d'annonces interstitielles de test /21775744923/example/interstitial.
    • Lorsque vous créez et testez votre application, assurez-vous d'utiliser des annonces tests plutôt que des annonces de production. Si vous n'utilisez pas l'ID de bloc d'annonces de test, Google peut suspendre votre compte.
    • Avant de publier votre application, remplacez cet ID par votre ID de bloc d'annonces.
    • Pour en savoir plus sur les annonces tests GMA Next-Gen SDK, consultez Activer les annonces tests.

Comprendre le préchargement des annonces (bêta)

Le préchargement des annonces (bêta) dans GMA Next-Gen SDK automatise le chargement et la mise en cache des annonces.

Le préchargement des annonces offre les avantages suivants :

  • Gestion des références : conserve les références jusqu'à ce que les annonces soient diffusées.
  • Rechargement automatique : charge une nouvelle annonce lorsqu'une annonce est récupérée à partir du cache.
  • Nouvelles tentatives gérées : charge une nouvelle annonce lorsqu'une annonce ne parvient pas à se charger.
  • Gestion de l'expiration : actualise les annonces avant leur expiration.
  • Optimisation du cache : optimise l'ordre du cache pour diffuser l'annonce la plus prioritaire.
Remarque : Pour charger des annonces manuellement, consultez Charger une seule annonce interstitielle.

Lancer le préchargement des annonces

Pour commencer à précharger les annonces, appelez la méthode start une fois au démarrage de l'application. Après avoir appelé la méthode start, GMA Next-Gen SDK précharge automatiquement les annonces et relance les requêtes ayant échoué pour les configurations préchargées.

L'exemple suivant montre comment commencer à précharger des annonces :

Kotlin

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Remplacez AD_UNIT_ID par l'ID de votre bloc d'annonces.

L'exemple précédent montre comment utiliser l'ID du bloc d'annonces comme ID de préchargement. Un ID de préchargement est une chaîne d'identification que vous créez pour identifier une configuration de préchargement d'annonces. Si votre application nécessite plusieurs configurations de ciblage pour le même ID de bloc d'annonces, transmettez un identifiant de chaîne personnalisé.

Obtenir et afficher l'annonce préchargée

Lorsque vous souhaitez afficher une annonce, appelez la méthode pollAd. GMA Next-Gen SDK récupère une annonce disponible et précharge automatiquement la suivante en arrière-plan. Si aucune annonce n'est disponible, GMA Next-Gen SDK ne renvoie aucune annonce.

Lorsque vous disposez d'un objet d'annonce, appelez la méthode show pour afficher l'annonce. L'exemple suivant montre comment récupérer et afficher une annonce préchargée :

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = InterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial 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.
  final InterstitialAd ad = InterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(activity);
}

Tant que vous n'êtes pas prêt à diffuser une annonce, évitez d'appeler la méthode pollAd. Pour lire les informations sur la réponse à l'annonce sans les afficher, consultez Lire les informations sur la réponse.

Écouter les événements publicitaires

Avant de diffuser l'annonce, écoutez les événements d'annonce. L'exemple suivant enregistre des rappels pour les événements publicitaires :

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

ad.adEventCallback =
  object : InterstitialAdEventCallback {
    override fun onAdShowedFullScreenContent() {
      // Interstitial ad did show.
    }

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

    override fun onAdFailedToShowFullScreenContent(
      fullScreenContentError: FullScreenContentError
    ) {
      // Interstitial ad failed to show.
      Log.e(TAG, "Interstitial ad failed to show: ${fullScreenContentError.message}")
    }

    override fun onAdImpression() {
      // Interstitial ad did record an impression.
    }

    override fun onAdClicked() {
      // Interstitial ad did record a click.
    }
  }

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

      @Override
      public void onAdDismissedFullScreenContent() {
        // Interstitial ad did dismiss.
        interstitialAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(
          @NonNull FullScreenContentError fullScreenContentError) {
        // Interstitial ad failed to show.
        Log.e(TAG, "Interstitial ad failed to show: " + fullScreenContentError.getMessage());
      }

      @Override
      public void onAdImpression() {
        // Interstitial ad did record an impression.
      }

      @Override
      public void onAdClicked() {
        // Interstitial ad did record a click.
      }
    });

Facultatif : Écouter les événements de préchargement

Lorsque vous commencez à précharger des annonces, inscrivez-vous aux événements de préchargement pour être averti lorsque les annonces sont préchargées avec succès, lorsque le préchargement échoue ou lorsque le cache d'annonces est épuisé.

L'exemple suivant montre comment s'inscrire aux événements d'annonces préchargées :

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
      }
    };

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

Lorsqu'une annonce ne se charge pas, GMA Next-Gen SDK précharge automatiquement les annonces et relance les requêtes ayant échoué pour les configurations préchargées.

Facultatif : Vérifier la disponibilité des annonces

Si vous avez besoin de savoir si une annonce est disponible, vérifiez sa disponibilité. L'exemple suivant vérifie si une annonce préchargée est disponible :

Kotlin

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

Java

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

Facultatif : Définir la taille de la mémoire tampon

La taille de la mémoire tampon contrôle le nombre d'annonces préchargées conservées en mémoire. Par défaut, Google optimise la taille de la mémoire tampon pour équilibrer la consommation de mémoire et la latence de diffusion des annonces. Vous pouvez définir une taille de mémoire tampon personnalisée pour augmenter le nombre d'annonces conservées en mémoire. Nous vous recommandons une taille de la mémoire tampon de deux annonces préchargées.

L'exemple suivant montre comment définir une taille de mémoire tampon :

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  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);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Limites du cache de préchargement

GMA Next-Gen SDK applique une limite à l'échelle de l'application au nombre total d'annonces préchargées pour tous les ID de blocs d'annonces et de préchargement :

  • Limite par défaut : Google conserve un maximum de six annonces préchargées en mémoire. Cette limite est partagée entre tous les formats et ID de préchargement.
  • Nous vous recommandons de conserver une taille de mémoire tampon de deux pour chaque ID de préchargement.

Facultatif : Arrêter le préchargement des annonces

Si vous n'avez plus besoin de diffuser des annonces pour un ID de préchargement spécifique dans la session, vous pouvez arrêter le préchargement des annonces. Pour arrêter le chargement des annonces pour un ID de préchargement spécifique, appelez la méthode destroy avec un ID de préchargement. L'appel de la méthode destroy supprime du cache toutes les annonces préchargées associées à l'ID de préchargement.

L'exemple suivant montre comment arrêter le préchargement des annonces :

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  InterstitialAdPreloader.destroy(adUnitId);
}

Facultatif : Lisez les informations sur la réponse.

Lisez les informations de réponse de la prochaine annonce préchargée sans supprimer l'annonce du cache.

L'exemple suivant montre comment lire les informations de réponse de la prochaine annonce préchargée :

Kotlin

val responseInfo = InterstitialAdPreloader.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 = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());