Annonces avec récompense

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les annonces avec récompense sont des annonces avec lesquelles les utilisateurs peuvent interagir en échange de récompenses dans l'application. Ce guide vous explique comment intégrer des annonces avec récompense d'AdMob dans une application Unity. Lisez les témoignages de nos clients : étude de cas 1, étude de cas 2.

Prérequis

Créer un objet d'annonce avec récompense

Les annonces avec récompense sont demandées et diffusées par RewardedAd objets. La première étape requise pour diffuser une annonce avec récompense consiste à instancier un objet RewardedAd en appelant le constructeur avec l'ID de bloc d'annonces à utiliser pour charger l'annonce. Cela est illustré dans l'extrait de code suivant:

Pour faciliter l'intégration des annonces à l'aide de l'éditeur Unity, essayez la nouvelle version bêta des emplacements d'annonce.

using UnityEngine.Events;
using UnityEngine;
using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine.UI;
using System;
using System.Collections.Generic;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);
    }
}

Toujours tester avec les annonces tests

Lorsque vous créez et testez vos applications, veillez à utiliser des annonces de test plutôt que des annonces de production. À défaut, votre compte risque d'être suspendu.

Pour charger les annonces tests, le plus simple est d'utiliser nos ID de blocs d'annonces tests dédiés pour les annonces avec récompense Android et iOS:

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Elles ont été spécialement configurées pour renvoyer des annonces tests à chaque demande, et vous êtes libre de les utiliser dans vos propres applications pour coder, tester et déboguer. Veillez simplement à les remplacer par votre propre ID de bloc d'annonces avant de publier votre application.

Pour en savoir plus sur le fonctionnement des annonces de test du SDK Mobile Ads, consultez la page Tester les annonces.

Charger une annonce

Pour charger une annonce avec récompense, appelez la méthode loadAd() de l'objet RewardedAd. Cette méthode nécessite une instance de AdRequest comme argument.

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        ...

        this.rewardedAd = new RewardedAd(adUnitId);

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }
}

[Facultatif] Valider les rappels de validation côté serveur

Les applications qui nécessitent des données supplémentaires dans les rappels de validation côté serveur doivent utiliser la fonctionnalité de données personnalisées des annonces avec récompense. Toute valeur de chaîne définie sur un objet d'annonce 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 ne sera pas présente dans le rappel SSV.

L'exemple de code suivant montre comment définir les options SSV après le chargement de l'annonce avec récompense.

void HandleRewardedAdLoaded(RewardedAd ad, AdFailedToLoadEventArgs error)
{
    // Create and pass the SSV options to the rewarded ad.
    var options = new ServerSideVerificationOptions
                          .Builder()
                          .SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
                          .Build()
    ad.SetServerSideVerificationOptions(options);
}

Si vous souhaitez définir la chaîne de récompenses personnalisée, vous devez le faire avant de diffuser l'annonce.

Événements d'annonce

Pour personnaliser davantage le comportement de votre annonce, vous pouvez l'associer à un certain nombre d'événements au cours de son cycle de vie: chargement, ouverture, fermeture, etc. Écoutez ces événements en enregistrant un délégué pour le gestionnaire d'événements approprié. L'événement le plus important, OnUserEarnedReward, est appelé lorsque l'utilisateur est rémunéré pour avoir regardé une vidéo. Vous pouvez aussi implémenter d'autres événements d'annonce, comme indiqué ci-dessous.

using GoogleMobileAds.Api;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void Start()
    {
        string adUnitId;
        #if UNITY_ANDROID
            adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        // Called when an ad request has successfully loaded.
        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        // Called when an ad request failed to load.
        this.rewardedAd.OnAdFailedToLoad += HandleRewardedAdFailedToLoad;
        // Called when an ad is shown.
        this.rewardedAd.OnAdOpening += HandleRewardedAdOpening;
        // Called when an ad request failed to show.
        this.rewardedAd.OnAdFailedToShow += HandleRewardedAdFailedToShow;
        // Called when the user should be rewarded for interacting with the ad.
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        // Called when the ad is closed.
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

    public void HandleRewardedAdLoaded(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdLoaded event received");
    }

    public void HandleRewardedAdFailedToLoad(object sender, AdFailedToLoadEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToLoad event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdOpening(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdOpening event received");
    }

    public void HandleRewardedAdFailedToShow(object sender, AdErrorEventArgs args)
    {
        MonoBehaviour.print(
            "HandleRewardedAdFailedToShow event received with message: "
                             + args.Message);
    }

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        MonoBehaviour.print("HandleRewardedAdClosed event received");
    }

    public void HandleUserEarnedReward(object sender, Reward args)
    {
        string type = args.Type;
        double amount = args.Amount;
        MonoBehaviour.print(
            "HandleRewardedAdRewarded event received for "
                        + amount.ToString() + " " + type);
    }
}

L'événement OnUserEarnedReward fournit des arguments d'événements spéciaux. Il transmet une instance de Reward avec un Type et un Amount décrivant la récompense accordée à l'utilisateur:

public void HandleUserEarnedReward(object sender, Reward args)
{
    string type = args.Type;
    double amount = args.Amount;
     MonoBehaviour.print(
          "HandleRewardedAdRewarded event received for "
              + amount.ToString() + " " + type);
}

Événements d'annonce disponibles

OnAdLoaded
Invoqué à la fin du chargement d'une annonce.
OnAdFailedToLoad
Invoqué en cas d'échec du chargement d'une annonce. La propriété Message du AdErrorEventArgs fourni décrit le type de l'échec.
OnAdOpening
Invoqué lorsque l'annonce s'affiche, couvrant l'écran de l'appareil. C'est un bon endroit pour mettre en pause la sortie audio de votre application ou votre boucle de jeu, si nécessaire.
OnAdFailedToShow
Appelé lorsqu'une annonce ne s'affiche pas. La propriété Message du AdErrorEventArgs fourni décrit le type de l'échec.
OnUserEarnedReward
Appelé lorsqu'un utilisateur doit être récompensé pour avoir regardé une vidéo. Le paramètre Reward décrit la récompense offerte à l'utilisateur.
OnAdClosed
Invoqué lorsque l'annonce vidéo avec récompense est fermée, car l'utilisateur a appuyé sur l'icône de fermeture ou a appuyé sur le bouton "Retour". Si votre application a mis en pause la sortie audio ou la boucle de jeu, vous pouvez la reprendre.

Diffuser l'annonce

Avant de diffuser une annonce avec récompense, les utilisateurs doivent pouvoir choisir explicitement de la regarder en échange d'une récompense. Les annonces avec récompense doivent toujours être une option d'activation.

Pour afficher une annonce avec récompense, vérifiez la méthode IsLoaded() pour vous assurer qu'elle est chargée, puis appelez show(). Voici comment procéder:

private void UserChoseToWatchAd()
{
  if (this.rewardedAd.IsLoaded()) {
    this.rewardedAd.Show();
  }
}

Utiliser OnAdClosed pour précharger la prochaine annonce avec récompense

RewardedAd est un objet à usage unique. Autrement dit, lorsqu'une annonce avec récompense est diffusée, l'objet ne peut pas être utilisé pour charger une autre annonce. Pour demander une autre annonce avec récompense, vous devez créer un objet RewardedAd.

Il est recommandé de charger une autre annonce avec récompense dans l'événement d'annonce OnAdClosed afin que la prochaine annonce avec récompense commence à se charger dès que l'annonce précédente est ignorée:

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd rewardedAd;
    ...

    public void CreateAndLoadRewardedAd()
    {
        #if UNITY_ANDROID
            string adUnitId = "ca-app-pub-3940256099942544/5224354917";
        #elif UNITY_IPHONE
            string adUnitId = "ca-app-pub-3940256099942544/1712485313";
        #else
            string adUnitId = "unexpected_platform";
        #endif

        this.rewardedAd = new RewardedAd(adUnitId);

        this.rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        this.rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        this.rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        this.rewardedAd.LoadAd(request);
    }

...

    public void HandleRewardedAdClosed(object sender, EventArgs args)
    {
        this.CreateAndLoadRewardedAd();
    }
}

Chargement de plusieurs annonces avec récompense

Pour charger plusieurs annonces avec récompense, suivez les étapes décrites dans les sections Créer un objet d'annonce avec récompense et Charger une annonce pour chaque annonce que vous souhaitez charger. L'extrait de code ci-dessous montre comment charger deux annonces avec récompense pour deux emplacements distincts.

...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    private RewardedAd gameOverRewardedAd;
    private RewardedAd extraCoinsRewardedAd;
    ...
    public void Start()
    {
        ...

        this.gameOverRewardedAd = CreateAndLoadRewardedAd(adUnitId);
        this.extraCoinsRewardedAd = CreateAndLoadRewardedAd(adUnitId);
    }

    public RewardedAd CreateAndLoadRewardedAd(string adUnitId)
    {
        RewardedAd rewardedAd = new RewardedAd(adUnitId);

        rewardedAd.OnAdLoaded += HandleRewardedAdLoaded;
        rewardedAd.OnUserEarnedReward += HandleUserEarnedReward;
        rewardedAd.OnAdClosed += HandleRewardedAdClosed;

        // Create an empty ad request.
        AdRequest request = new AdRequest.Builder().Build();
        // Load the rewarded ad with the request.
        rewardedAd.LoadAd(request);
        return rewardedAd;
    }
}

Exemples