Configurer des annonces avec récompense

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

Les annonces avec récompense vous permettent de récompenser les utilisateurs qui interagissent avec des annonces vidéo, des annonces jouables et des enquêtes en leur offrant différents éléments intégrés au sein de votre application.

Ce guide explique comment intégrer des annonces avec récompense 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 avec récompense test ca-app-pub-3940256099942544/5224354917.
    • 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 du bloc d'annonces test, Google peut suspendre votre compte.
    • 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 (bêta)

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 qu'elles n'expirent.
  • 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 start une seule fois lorsque vous initialisez GMA Next-Gen SDK. Une fois que vous avez appelé la start méthode, 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

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

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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 des 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é.

Le préchargement des annonces n'est pas compatible avec la modification des paramètres de ciblage ni des demandes d'annonces. Si vous devez modifier les paramètres de ciblage entre les requêtes, utilisez le chargement unique.

Obtenir et afficher l'annonce préchargée

Avant d'afficher l'annonce, appelez la méthode pollAd. Ne stockez pas l'objet d'annonce préchargé. Lorsque vous appelez la pollAd méthode, 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 afficher 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 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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

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

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

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

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

Lorsque votre application atteint un emplacement d'annonce et peut appeler la méthode show, appelez la méthode pollAd. N'appelez pas la méthode pollAd dans les rappels de préchargement ni après avoir vérifié la méthode isAdAvailable pour conserver une annonce. Si vous devez inspecter les métadonnées de l'annonce avant de l'afficher, lisez les informations de réponse sans supprimer l'annonce du cache.

Écouter les événements d'annonce

Avant d'afficher l'annonce, écoutez les événements d'annonce. L'exemple suivant enregistre les rappels pour les événements d'annonce :

Kotlin

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

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

Pour transmettre le contexte utilisateur et applicatif dans les rappels de validation côté serveur (SSV), définissez les options de validation sur l'objet d'annonce avant d'afficher l'annonce. Étant donné que les rappels SSV arrivent sur votre serveur depuis Google sans état de session, ajoutez les chaînes facultatives suivantes. Google transfère ces chaînes sans les modifier en tant que paramètres de requête signés dans le rappel SSV.

  • Paramètre de requête user_id : identifie l'utilisateur à créditer, par exemple un ID de compte interne.
  • Paramètre de requête custom_data : contient des données d'application, telles que l'emplacement de la récompense, le niveau de jeu ou un nonce généré par le serveur.

Si vous ne définissez pas de valeur, Google omet ce paramètre de requête du rappel SSV.

L'exemple suivant définit des données personnalisées sur un objet d'annonce avant d'afficher l'annonce :

Kotlin

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

Java

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

Remplacez SAMPLE_CUSTOM_DATA_STRING par vos données personnalisées.

Attention : Le paramètre de requête custom_data est encodé en pourcentage. Avant d'analyser la valeur, décodez l'URL de la chaîne sur votre serveur et vérifiez la signature du rappel avant de faire confiance aux paramètres de requête user_id ou custom_data.

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 à être préchargées 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 =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

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

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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. N'appelez pas de requêtes de chargement manuel dans les rappels d'échec. Dans les méthodes de rappel d'événement de préchargement, n'appelez pas les méthodes pollAd, destroy ni start. L'appel de ces méthodes dans les rappels peut entraîner des boucles de chargement récursives.

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 RewardedAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.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 ou diminuer 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. Si la majeure partie de votre trafic provient d'appareils à faible mémoire, réduisez la taille de la mémoire tampon.

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

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)
RewardedAdPreloader.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);
RewardedAdPreloader.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 pour chaque ID de préchargement.

Facultatif : Arrêter le préchargement des annonces

Maintenez le préchargement actif pendant que votre application diffuse des annonces. Pendant ce temps, n'utilisez pas la méthode destroy. Si vous n'avez plus besoin d'afficher 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.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

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

Facultatif : Lire les informations de réponse

Lisez les informations de réponse de la prochaine annonce préchargée sans supprimer l'annonce du cache. Si vous devez inspecter les métadonnées de l'annonce avant de l'afficher, lisez les informations de réponse au lieu d'appeler la méthode pollAd.

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

Kotlin

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

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