Configurer des annonces interstitielles avec récompense

SDK Next-Gen.

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

Les annonces interstitielles avec récompense sont un format qui vous permet de proposer des récompenses pour les annonces diffusées automatiquement lors des transitions naturelles dans les applications. Contrairement aux annonces avec récompense, les utilisateurs ne sont pas obligés de choisir de regarder un interstitiel avec récompense. Pour en savoir plus, consultez les consignes concernant les interstitiels avec récompense.

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

Avant de commencer

Avant de continuer, procédez comme suit :

  • Configurez GMA Next-Gen SDK.
  • Utilisez l'ID du bloc d'annonces interstitielles avec récompense test ca-app-pub-3940256099942544/5354046379.
    • Lorsque vous créez et testez votre application, assurez-vous d'utiliser des annonces tests plutôt que des annonces de production. Sinon, votre compte pourrait être suspendu.
    • Avant de publier votre application, remplacez cet ID par l'ID de votre 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

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

Le préchargement des annonces présente 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.

Démarrer le préchargement des annonces

Pour commencer à précharger des annonces, appelez la méthode startPreload() une seule fois au démarrage de l'application. Une fois que vous avez appelé la méthode startPreload(), GMA Next-Gen SDK précharge automatiquement les annonces et retente les requêtes ayant échoué pour les configurations préchargées.

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

Kotlin

// 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)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// 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);
RewardedInterstitialAdPreloader.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 un identifiant de chaîne que vous créez pour identifier une configuration de préchargement d'annonce. 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 diffuser une annonce, appelez la méthode pollAd(). GMA Next-Gen SDK récupère une annonce disponible et précharge automatiquement l'annonce suivante en arrière-plan. Si aucune annonce n'est disponible, GMA Next-Gen SDK n'en renvoie aucune.

Lorsque vous disposez d'un objet d'annonce disponible, appelez la méthode show pour diffuser l'annonce. Utilisez un écouteur de récompense pour gérer les événements de récompense. L'exemple suivant montre comment récupérer et diffuser 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 = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

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

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

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

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

Écouter les événements d'annonce

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

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

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

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

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

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

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

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

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

Facultatif : Valider les rappels de validation côté serveur (SSV)

Si votre application nécessite des données supplémentaires dans les rappels de validation côté serveur, utilisez la fonctionnalité de données personnalisées des annonces interstitielles avec récompense. Toute valeur de chaîne définie sur un objet d'annonce interstitielle avec récompense est transmise au paramètre de requête custom_data du rappel SSV. Si aucune valeur de données personnalisées n'est définie, la valeur du paramètre de requête custom_data n'est pas présente dans le rappel SSV.

L'exemple de code suivant montre comment définir des données personnalisées sur un objet d'annonce interstitielle avec récompense avant de diffuser l'annonce :

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

Remplacez SAMPLE_CUSTOM_DATA_STRING par vos données personnalisées.

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

Lorsque vous commencez à précharger des annonces, enregistrez-vous pour les événements de préchargement afin d'être averti lorsque les annonces sont préchargées, ne parviennent pas à se précharger ou lorsque le cache d'annonces est épuisé.

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

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,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded 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, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.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(
                "Rewarded 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, "Rewarded 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, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Lorsqu'une annonce ne parvient pas à se charger, GMA Next-Gen SDK précharge automatiquement les annonces et retente 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 montre comment vérifier si une annonce préchargée est disponible :

Kotlin

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

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.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 mémoire tampon maximale de 4.

L'exemple suivant montre comment définir une taille de mémoire tampon de quatre annonces préchargées :

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

Limites du cache de préchargement

GMA Next-Gen SDK applique une limite à l'échelle de l'application sur le nombre total d'annonces préchargées pour tous les blocs d'annonces et tous les ID 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 tous les ID de préchargement.
  • Nous vous recommandons de conserver une taille de mémoire tampon de deux ou trois par 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.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

Java

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

Facultatif : Lire les informations de réponse

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

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

Kotlin

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

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