Commencer

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 terminé, téléchargez l'application exemple PAL pour tvOS.

Ajouter le SDK PAL à votre projet

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

Le SDK de la bibliothèque d'accès programmatique 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 la version majeure suivante.

Une fois que vous avez terminé, Xcode résout les dépendances de packages et les télécharge en arrière-plan. Pour en savoir plus sur l'ajout de dépendances de packages, 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écharger et extraire le SDK PAL pour iOS
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 nécessite que chaque nouvelle requête de flux soit accompagnée d'un nonce nouvellement généré. Cependant, les nonces peuvent être réutilisés pour plusieurs demandes d'annonces au sein du même flux.

Tous les extraits de code ci-dessous sont des modifications apportées à ViewController.m dans l'application exemple 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. Ainsi, le corrélateur de la page, ou paramètre &correlator, reste inchangé pendant toute la durée de vie d'une page ou pendant la session d'un utilisateur de l'application.

Vous avez toujours le contrôle sur le corrélateur de flux, ou &scor, qui doit être réinitialisé une fois pour chaque nouveau flux. Toutes les demandes d'annonces d'un même flux doivent partager la même valeur PALNonceLoader et la même valeur 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 bouchons pour les deux méthodes déléguées:

@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 'allowStorage' and
  // 'directedForChildOrUnknownAge' is 'NO', but should be updated once the
  // appropriate consent has been gathered. Publishers should either
  // integrate with a CMP or use a different method to handle storage consent.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.allowStorage = YES;
  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 {
}

Lancez ensuite une requête 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.
 */
- (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 integer. See reference docs for more details.
  NSInteger SampleAPIFramework = 501;
  request.supportedApiFrameworks = [NSMutableSet setWithArray:@[ SampleAPIFramework ]];
  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, renseignez les délégués du chargeur de nonce pour consigner les nonces générés:

#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 sécurisé pour les URL. Vous n'avez pas besoin de l'encoder en URL.

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

Enfin, vous devez ajouter des méthodes pour gérer l'envoi des informations de session de lecture de contenu et des clics au SDK. Consultez l'exemple suivant pour implémenter les 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émarrage du lecteur vidéo lorsque la lecture commence pour la première fois, en réponse à une action déclenchée par l'utilisateur (click-to-play) ou à une action déclenchée par l'application (lecture automatique). sendPlaybackEnd doit être appelé à la fin de la lecture, et sendAdClick doit être appelé chaque fois que l'utilisateur 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 à partir du SDK PAL vers vos serveurs intermédiaires, puis vers Google Ad Manager. Cela permet d'améliorer la monétisation via 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 inclure le nonce dans la requête du serveur adressée à Ad Manager. Voici un exemple de tag d'emplacement publicitaire 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 nonce. L'ad server tiers doit prendre en charge une macro qui lui est propre, telle que %%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 sur la procédure à suivre, consultez la documentation de l'ad server tiers.