Annonces avec récompense

Les annonces avec récompense sont des annonces avec lesquelles les utilisateurs ont la possibilité d'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.

Voici quelques témoignages de clients : étude de cas 1, étude de cas 2.

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

Prérequis

• Suivez le guide de démarrage.

Toujours tester avec des annonces tests

L'exemple de code suivant contient un ID de bloc d'annonces que vous pouvez utiliser pour demander des annonces tests. Il est spécialement configuré pour renvoyer des annonces tests plutôt que des annonces de production pour chaque demande, ce qui permet de l'utiliser en toute sécurité.

Toutefois, après avoir enregistré une application dans l'interface WebAdMob et créé vos propres ID de bloc d'annonces à utiliser dans votre application, configurez explicitement votre appareil en tant qu'appareil de test lors du développement.

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

Initialiser le SDK Mobile Ads

Avant de charger des annonces, demandez à votre application d'initialiser le SDK Mobile Ads en appelant MobileAds.Initialize(). Cette opération ne doit être effectuée qu'une seule fois, idéalement au lancement de l'application.

using GoogleMobileAds;
using GoogleMobileAds.Api;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    public void Start()
    {
        // Initialize the Google Mobile Ads SDK.
        MobileAds.Initialize((InitializationStatus initStatus) =>
        {
            // This callback is called once the MobileAds SDK is initialized.
        });
    }
}

Si vous utilisez la médiation, attendez que le rappel se produise avant de charger les annonces, car cela garantit que tous les adaptateurs de médiation sont initialisés.

Implémentation

Voici les principales étapes à suivre pour intégrer des annonces avec récompense:

1. Charger l'annonce avec récompense
2. [Facultatif] Valider les rappels de validation côté serveur (SSV)
3. Diffuser l'annonce avec récompense avec rappel de récompense
4. Écouter les événements d'annonces avec récompense
5. Faire le tri dans l'annonce avec récompense
6. Précharger la prochaine annonce avec récompense

Charger l'annonce avec récompense

Pour charger une annonce avec récompense, vous devez utiliser la méthode statique Load() sur la classe RewardedAd. L'objet RewardedAd chargé est fourni en tant que paramètre dans le gestionnaire d'achèvement. L'exemple ci-dessous montre comment charger un RewardedAd.

  // These ad units are configured to always serve test ads.
#if UNITY_ANDROID
  private string _adUnitId = "ca-app-pub-3940256099942544/5224354917";
#elif UNITY_IPHONE
  private string _adUnitId = "ca-app-pub-3940256099942544/1712485313";
#else
  private string _adUnitId = "unused";
#endif

  private RewardedAd _rewardedAd;

  /// <summary>
  /// Loads the rewarded ad.
  /// </summary>
  public void LoadRewardedAd()
  {
      // Clean up the old ad before loading a new one.
      if (_rewardedAd != null)
      {
            _rewardedAd.Destroy();
            _rewardedAd = null;
      }

      Debug.Log("Loading the rewarded ad.");

      // create our request used to load the ad.
      var adRequest = new AdRequest();

      // send the request to load the ad.
      RewardedAd.Load(_adUnitId, adRequest,
          (RewardedAd ad, LoadAdError error) =>
          {
              // if error is not null, the load request failed.
              if (error != null || ad == null)
              {
                  Debug.LogError("Rewarded ad failed to load an ad " +
                                 "with error : " + error);
                  return;
              }

              Debug.Log("Rewarded ad loaded with response : "
                        + ad.GetResponseInfo());

              _rewardedAd = ad;
          });
  }

Avertissement :Nous vous déconseillons vivement d'essayer de charger une nouvelle annonce à partir du bloc d'exécution de la demande d'annonce en cas d'échec du chargement. Si vous devez charger une annonce à partir du blocage des demandes d'annonces, limitez les nouvelles tentatives de chargement d'annonces pour éviter les échecs continus de demandes d'annonces dans des situations telles que la connectivité réseau limitée.

Conseil:Vous pouvez utiliser les appels de volume d'annonces pour créer un cache d'annonces préchargées avant de vouloir les diffuser, afin que les annonces puissent être diffusées sans latence lorsque cela est nécessaire. Étant donné que les annonces expirent au bout d'une heure, vous devez vider ce cache et actualiser la page avec de nouvelles annonces toutes les heures.

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

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 de validation côté serveur une fois l'annonce avec récompense chargée.

// send the request to load the ad.
RewardedAd.Load(_adUnitId, adRequest, (RewardedAd ad, LoadAdError error) =>
{
    // If the operation failed, an error is returned.
    if (error != null || ad == null)
    {
        Debug.LogError("Rewarded ad failed to load an ad with error : " + error);
        return;
    }

    // If the operation completed successfully, no error is returned.
    Debug.Log("Rewarded ad loaded with response : " + ad.GetResponseInfo());

    // 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écompense personnalisée, vous devez le faire avant de diffuser l'annonce.

Important :La chaîne de récompense personnalisée contient un pourcentage d'échappement et peut nécessiter un décodage lorsqu'elle est analysée à partir du rappel de la fonctionnalité de validation côté serveur.

Diffuser l'annonce avec récompense avec rappel de récompense

Lorsque vous présentez votre annonce, vous devez fournir un rappel pour gérer la récompense proposée à l'utilisateur. Les annonces ne peuvent être diffusées qu'une seule fois par chargement. Utilisez la méthode CanShowAd() pour vérifier que l'annonce est prête à être diffusée.

Le code suivant présente la meilleure méthode pour diffuser une annonce avec récompense.

public void ShowRewardedAd()
{
    const string rewardMsg =
        "Rewarded ad rewarded the user. Type: {0}, amount: {1}.";

    if (rewardedAd != null && rewardedAd.CanShowAd())
    {
        rewardedAd.Show((Reward reward) =>
        {
            // TODO: Reward the user.
            Debug.Log(String.Format(rewardMsg, reward.Type, reward.Amount));
        });
    }
}

Écouter les événements d'annonces avec récompense

Pour personnaliser davantage le comportement de votre annonce, vous pouvez vous connecter à un certain nombre d'événements qui en découlent: l'ouverture, la fermeture, etc. Écoutez ces événements en enregistrant un délégué, comme indiqué ci-dessous.

private void RegisterEventHandlers(RewardedAd ad)
{
    // Raised when the ad is estimated to have earned money.
    ad.OnAdPaid += (AdValue adValue) =>
    {
        Debug.Log(String.Format("Rewarded ad paid {0} {1}.",
            adValue.Value,
            adValue.CurrencyCode));
    };
    // Raised when an impression is recorded for an ad.
    ad.OnAdImpressionRecorded += () =>
    {
        Debug.Log("Rewarded ad recorded an impression.");
    };
    // Raised when a click is recorded for an ad.
    ad.OnAdClicked += () =>
    {
        Debug.Log("Rewarded ad was clicked.");
    };
    // Raised when an ad opened full screen content.
    ad.OnAdFullScreenContentOpened += () =>
    {
        Debug.Log("Rewarded ad full screen content opened.");
    };
    // Raised when the ad closed full screen content.
    ad.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Rewarded ad full screen content closed.");
    };
    // Raised when the ad failed to open full screen content.
    ad.OnAdFullScreenContentFailed += (AdError error) =>
    {
        Debug.LogError("Rewarded ad failed to open full screen content " +
                       "with error : " + error);
    };
}

Faire le tri dans l'annonce avec récompense

Lorsque vous avez terminé avec une RewardedAd, veillez à appeler la méthode Destroy() avant de supprimer votre référence à celle-ci:

_rewardedAd.Destroy();

Cela informe le plug-in que l'objet n'est plus utilisé et que la mémoire occupée peut être récupérée. L'échec de l'appel de cette méthode entraîne des fuites de mémoire.

Précharger la prochaine annonce avec récompense

RewardedAd est un objet à usage unique. Cela signifie qu'une fois qu'une annonce avec récompense a été diffusée, l'objet ne peut plus être réutilisé. Pour demander une autre annonce avec récompense, vous devez créer un objet RewardedAd.

Pour préparer une annonce avec récompense pour la prochaine impression, préchargez l'annonce avec récompense une fois que l'événement d'annonce OnAdFullScreenContentClosed ou OnAdFullScreenContentFailed est déclenché.

private void RegisterReloadHandler(RewardedAd ad)
{
    // Raised when the ad closed full screen content.
    ad.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Rewarded Ad full screen content closed.");

        // Reload the ad so that we can show another as soon as possible.
        LoadRewardedAd();
    };
    // Raised when the ad failed to open full screen content.
    ad.OnAdFullScreenContentFailed += (AdError error) =>
    {
        Debug.LogError("Rewarded ad failed to open full screen content " +
                       "with error : " + error);

        // Reload the ad so that we can show another as soon as possible.
        LoadRewardedAd();
    };
}

Ressources supplémentaires

• Exemple HelloWorld : implémentation minimale de tous les formats d'annonces.