Débuter

Prérequis

• Xcode 13 ou version ultérieure

Ce guide explique comment appeler le SDK PAL pour recevoir un nonce et surveiller les événements de lecture. Pour suivre le guide complet, téléchargez l'exemple d'application PAL pour tvOS.

Ajouter le SDK PAL à votre projet

Installer le SDK PAL à l'aide de Swift Package Manager

Le SDK Programmatic Access Library est compatible avec Swift Package Manager à partir de la version 2.5.3. Suivez les étapes ci-dessous pour importer le package Swift.

1. Dans Xcode, installez le package Swift du SDK IMA en accédant à File > Add Packages… (Fichier > Ajouter des packages…).

2. Dans l'invite qui s'affiche, recherchez le dépôt GitHub du package Swift du SDK IMA :

   https://github.com/googleads/swift-package-manager-google-programmatic-access-library-tvos
   

3. Sélectionnez la version du package Swift du SDK PAL que vous souhaitez utiliser. Pour les nouveaux projets, nous vous recommandons d'utiliser Jusqu'à la prochaine version majeure.

Une fois que vous avez terminé, Xcode résout les dépendances de votre package et les télécharge en arrière-plan. Pour savoir comment ajouter des dépendances de package, consultez l'article d'Apple.

Télécharger et installer manuellement le SDK PAL

Si vous ne souhaitez pas utiliser Swift Package Manager, vous pouvez télécharger le SDK PAL et l'ajouter manuellement à votre projet.

1. Téléchargez et extrayez le SDK PAL pour tvOS.
2. Suivez le guide du développeur Apple pour intégrer le framework à votre projet.

Générer un nonce

Un "nonce" est une chaîne chiffrée unique générée par PAL à l'aide de PALNonceLoader. Le SDK PAL exige que chaque nouvelle demande de flux soit accompagnée d'un nonce nouvellement généré. Toutefois, les nonces peuvent être réutilisés pour plusieurs demandes d'annonces dans le même flux.

Tous les extraits de code ci-dessous sont des modifications apportées à ViewController.m dans l'exemple d'application PAL pour tvOS.

Pour demander un nonce, commencez par importer la bibliothèque PAL :

@import ProgrammaticAccessLibrary;

Remarque : Nous vous recommandons de ne créer qu'une seule instance de la classe PALNonceLoader pour chaque session utilisateur dans votre application, sauf si celle-ci comporte plusieurs pages ou des constructions équivalentes. Cela permet de conserver le corrélateur de page, ou paramètre &correlator, inchangé pendant toute la durée de vie d'une page ou de la session d'un utilisateur dans l'application.

Vous contrôlez toujours le corrélateur de flux, ou &scor, qui doit être réinitialisé une fois pour chaque nouveau flux. Toutes les demandes d'annonces du même flux doivent partager la même valeur de PALNonceLoader et de corrélateur de flux pour que les fonctionnalités de limitation de la fréquence d'exposition et d'exclusion réciproque fonctionnent correctement.

Ensuite, créez une instance de PALNonceLoader et ajoutez des stubs pour les deux méthodes de délégué :

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The view in which a video would play.
// In this sample, it is mocked for simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void) viewDidLoad {
  [super viewDidLoad];
  // The default value for 'directedForChildOrUnknownAge' is
  // 'NO'. Update the value after the appropriate consent has been gathered.
  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `PALSettings.forceLimitedAds` property.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.directedForChildOrUnknownAge = NO;

  self.nonceLoader = [[PALNonceLoader alloc] initWithSettings:settings];
  self.nonceLoader.delegate = self;
}

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
}

Ensuite, lancez une demande de nonce, renseignez ses propriétés et utilisez-la pour initialiser un gestionnaire de nonce :

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The nonce manager result from the last successful nonce request.
@property(nonatomic) PALNonceManager *nonceManager;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end

...

- (void)viewDidLoad {
  ...
  self.nonceLoader.delegate = self;
  [self requestNonceManager];
}

...

#pragma mark - UI Callback methods

/**
 * Requests a new nonce manager with a request containing arbitrary test values
 * like a (sane) user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 *
 * The PALNonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
- (void)requestNonceManager {
  PALNonceRequest *request = [[PALNonceRequest alloc] init];
  request.continuousPlayback = PALFlagOff;
  request.descriptionURL = [NSURL URLWithString:@"https://example.com/desc?key=val"];
  request.iconsSupported = YES;
  request.playerType = @"AwesomePlayer";
  request.playerVersion = @"4.2.1";
  request.PPID = @"123987456";
  request.sessionID = @"Sample SID";
  // Sample API framework integers. See reference docs for more details.
  request.supportedAPIFrameworks = [NSMutableSet setWithArray:@[ @2, @7, @9 ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;

  if (self.nonceManager) {
    // Detach the old nonce manager's gesture recognizer before destroying it.
    [self.videoView removeGestureRecognizer:self.nonceManager.gestureRecognizer];
    self.nonceManager = nil;
  }
  [self.nonceLoader loadNonceManagerWithRequest:request];
}

Enfin, remplissez les délégués du chargeur de nonce pour enregistrer les nonces générées :

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
  NSLog(@"Programmatic access nonce: %@", nonceManager.nonce);
  // Capture the created nonce manager and attach its gesture recognizer to the video view.
  self.nonceManager = nonceManager;
  [self.videoView addGestureRecognizer:self.nonceManager.gestureRecognizer];
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
  NSLog(@"Error generating programmatic access nonce: %@", error);
}

Lorsque vous effectuez votre appel VAST direct (DVC), définissez votre nonce comme valeur du paramètre givn. Le nonce est adapté aux URL. Vous n'avez pas besoin de l'encoder en URL.

Important : Si vous avez déjà fourni un nonce à l'aide du paramètre paln, nous vous recommandons vivement de passer à givn et d'arrêter d'envoyer paln. Si les deux paramètres sont inclus, le comportement n'est pas défini concernant le nonce utilisé.

Enfin, vous devez ajouter des méthodes pour gérer l'envoi d'informations sur la session de lecture de contenu et les clics au SDK. Consultez l'exemple suivant d'implémentation des méthodes sendPlaybackStart, sendPlaybackEnd et sendAdClick :

...

// Reports the start of playback for the current content session.
- (void)sendPlaybackStart {
  [self.nonceManager sendPlaybackStart];
}

// Reports the end of playback for the current content session.
- (void)sendPlaybackEnd {
  [self.nonceManager sendPlaybackEnd];
}

// Reports an ad click for the current nonce manager, if not nil.
- (void)sendAdClick {
  [self.nonceManager sendAdClick];
}

Dans votre implémentation, sendPlaybackStart doit être appelé au début de la lecture de la vidéo, en réponse à une action initiée par l'utilisateur (click-to-play) ou par l'application (lecture automatique). sendPlaybackEnd doit être appelé à la fin de la lecture, et sendAdClick doit être appelé chaque fois que le spectateur clique sur une annonce.

(Facultatif) Envoyer des signaux Google Ad Manager via des ad servers tiers

Configurez la demande de l'ad server tiers pour Ad Manager. Une fois les étapes suivantes effectuées, le paramètre nonce se propage du SDK PAL à Google Ad Manager, en passant par vos serveurs intermédiaires. Cela permet une meilleure monétisation grâce à Google Ad Manager.

Remarque : Si vous utilisez plusieurs solutions tierces (par exemple, un serveur SSAI tiers appelant un autre ad server tiers), vous devez vous assurer que le nonce chiffré du SDK PAL est transmis à chaque tiers.

Configurez votre ad server tiers pour qu'il inclue le nonce dans la demande du serveur envoyée à Ad Manager. Voici un exemple de tag d'annonce configuré dans l'ad server tiers :

https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...

Pour en savoir plus, consultez le guide d'implémentation côté serveur de Google Ad Manager.

Ad Manager recherche givn= pour identifier la valeur du nonce. L'ad server tiers doit accepter une de ses propres macros, comme %%custom_key_for_google_nonce%%, et la remplacer par le paramètre de requête nonce que vous avez fourni à l'étape précédente. Pour en savoir plus, consultez la documentation de l'ad server tiers.