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 depuis Ad Manager dans une application iOS.

Conditions préalables

Toujours tester avec des annonces tests

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

Le moyen le plus simple de charger des annonces tests consiste à utiliser notre ID de bloc d'annonces test dédié aux annonces avec récompense iOS:

/6499/example/rewarded

Cet outil a été spécialement configuré pour renvoyer des annonces tests pour chaque requête. Vous êtes libre de l'utiliser dans vos propres applications lors du codage, des tests et du débogage. Veillez simplement à le remplacer par votre propre ID de bloc d'annonces avant de publier votre application.

Pour en savoir plus sur le fonctionnement des annonces tests du SDK Mobile Ads, consultez Annonces tests.

Implémentation

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

  • Charger une annonce
  • [Facultatif] Valider les rappels de validation côté serveur
  • S'inscrire pour recevoir des rappels
  • Afficher l'annonce et gérer l'événement lié à la récompense

Charger une annonce

Pour charger une annonce, vous devez utiliser la méthode statique loadWithAdUnitID:request:completionHandler: sur la classe GADRewardedAd. La méthode de chargement nécessite votre ID de bloc d'annonces, un objet GAMRequest et un gestionnaire d'achèvement appelé lorsque le chargement de l'annonce réussit ou échoue. L'objet GADRewardedAd chargé est fourni en tant que paramètre dans le gestionnaire d'achèvement. L'exemple suivant montre comment charger un GADRewardedAd dans votre classe ViewController.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/6499/example/rewarded"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
      }];
}

[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 de validation côté serveur. 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 des données personnalisées sur un objet d'annonce avec récompense avant de demander une annonce.

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedAd
     loadWithAdUnitID:@"/6499/example/rewarded"
              request:[GAMRequest request];
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

S'inscrire pour recevoir des rappels

Afin de recevoir des notifications pour les événements de présentation, vous devez implémenter le protocole GADFullScreenContentDelegate et l'attribuer à la propriété fullScreenContentDelegate de l'annonce renvoyée. Le protocole GADFullScreenContentDelegate gère les rappels lorsque l'annonce est bien présentée ou non, et lorsqu'elle est ignorée. Le code suivant montre comment implémenter le protocole et l'attribuer à l'annonce:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }

  /// Tells the delegate that the ad failed to present full screen content.
  func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
    print("Ad did fail to present full screen content.")
  }

  /// Tells the delegate that the ad will present full screen content.
  func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad will present full screen content.")
  }

  /// Tells the delegate that the ad dismissed full screen content.
  func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad did dismiss full screen content.")
  }
}

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
        self.rewardedAd.fullScreenContentDelegate = self;
      }];
}

/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
    didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
    NSLog(@"Ad did fail to present full screen content.");
}

/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad will present full screen content.");
}

/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad did dismiss full screen content.");
}

GADRewardedAd est un objet à usage unique. Cela signifie qu'une fois qu'une annonce avec récompense a été diffusée, elle ne peut plus être diffusée à nouveau. Une bonne pratique consiste à charger une autre annonce avec récompense dans la méthode adDidDismissFullScreenContent: sur GADFullScreenContentDelegate afin que l'annonce avec récompense suivante commence à se charger dès que la précédente est ignorée.

Afficher l'annonce et gérer l'événement lié à la récompense

Avant de diffuser une annonce avec récompense auprès des utilisateurs, vous devez leur proposer explicitement de visionner le contenu de cette annonce en échange d'une récompense. Les annonces avec récompense doivent toujours être activées.

Lorsque vous présentez votre annonce, vous devez fournir un objet GADUserDidEarnRewardHandler pour gérer la récompense pour l'utilisateur.

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

Swift

func show() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  // The UIViewController parameter is an optional.
  ad.present(fromRootViewController: nil) {
    let reward = ad.adReward
    print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

Objective-C

- (void)show {
  if (self.rewardedAd) {
    // The UIViewController parameter is nullable.
    [self.rewardedAd presentFromRootViewController:nil
                                  userDidEarnRewardHandler:^{
                                  GADAdReward *reward =
                                      self.rewardedAd.adReward;
                                  // TODO: Reward the user!
                                }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

Questions fréquentes

Puis-je obtenir les détails de la récompense GADRewardedAd ?
Oui. Si vous avez besoin du montant de la récompense avant le déclenchement du rappel userDidEarnReward, GADRewardedAd dispose d'une propriété adReward que vous pouvez vérifier pour vérifier le montant de la récompense une fois l'annonce chargée.
Existe-t-il un délai avant expiration pour l'appel d'initialisation ?
Au bout de 10 secondes, le SDK Google Mobile Ads appelle la méthode GADInitializationCompletionHandler fournie à la méthode startWithCompletionHandler:, même si un réseau de médiation n'a toujours pas terminé l'initialisation.
Que faire si certains réseaux de médiation ne sont pas prêts lorsque je reçois le rappel d'initialisation ?

Nous vous recommandons de charger une annonce dans GADInitializationCompletionHandler. Même si un réseau de médiation n'est pas prêt, le SDK Google Mobile Ads lui demande une annonce. Ainsi, si l'initialisation d'un réseau de médiation se termine après le délai d'inactivité, il peut toujours traiter les futures demandes d'annonces au cours de cette session.

Vous pouvez continuer à interroger l'état d'initialisation de tous les adaptateurs tout au long de votre session d'application en appelant GADMobileAds.initializationStatus.

Comment savoir pourquoi un réseau de médiation donné n'est pas prêt ?

La propriété description d'un objet GADAdapterStatus décrit la raison pour laquelle un adaptateur n'est pas prêt à traiter les demandes d'annonces.

Le gestionnaire d'achèvement userDidEarnRewardHandler est-il toujours appelé avant la méthode déléguée adDidDismissFullScreenContent: ?

Pour les annonces Google, tous les appels userDidEarnRewardHandler ont lieu avant le adDidDismissFullScreenContent:. Pour les annonces diffusées via la médiation, l'implémentation du SDK du réseau publicitaire tiers détermine l'ordre de rappel. Pour les SDK de réseaux publicitaires qui fournissent une seule méthode de délégation avec les informations sur les récompenses, l'adaptateur de médiation appelle userDidEarnRewardHandler avant adDidDismissFullScreenContent:.

Exemples sur GitHub

Étapes suivantes

En savoir plus sur la confidentialité des utilisateurs