开始使用

前提条件

• Xcode 13 或更高版本

本指南介绍了如何调用 PAL SDK 以接收随机数和监控播放事件。如需按照完整指南操作，请下载 PAL tvOS 示例应用。

将 PAL SDK 添加到您的项目

使用 Swift Package Manager 安装 PAL SDK

程序化访问库 SDK 支持 2.5.3 及更高版本的 Swift Package Manager。请按照以下步骤导入 Swift 软件包。

1. 在 Xcode 中，依次前往 File（文件）> Add Packages…（添加软件包…），安装 IMA SDK Swift 软件包。

2. 在出现的提示中，搜索 IMA SDK Swift 软件包的 GitHub 代码库：

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

3. 选择要使用的 PAL SDK Swift 软件包版本。 对于新项目，我们建议使用 Up to Next Major Version（更新至下一主要版本前的最新版）规则。

完成之后，Xcode 会解析您的软件包依赖项，并在后台下载它们。如需详细了解如何添加软件包依赖项，请参阅 Apple 的文章。

手动下载并安装 PAL SDK

如果您不想使用 Swift Package Manager，可以下载 PAL SDK 并手动将其添加到项目中。

1. 下载并提取 PAL SDK for tvOS
2. 按照 Apple 开发者指南将该框架纳入您的项目中。

生成 Nonce

“nonce”是 PAL 使用 PALNonceLoader 生成的单个加密字符串。PAL SDK 要求每个新的流请求都附带新生成的随机数。不过，在同一视频流中，nonce 可重复用于多个广告请求。

以下所有代码段都是对 PAL tvOS 示例应用中的 ViewController.m 所做的修改。

如需请求随机数，请先导入 PAL 库：

@import ProgrammaticAccessLibrary;

注意： 除非您的应用包含多个网页或等效的构造，否则我们建议您仅为应用中的每个用户会话创建一个 PALNonceLoader 类实例。这样一来，网页相关性标识符（即 &correlator 参数）在网页的整个生命周期内或用户使用应用的整个会话期间都保持不变。

您仍然可以控制流相关器（即 &scor），该相关器应针对每个新流重置一次。同一视频流的所有广告请求应共享相同的 PALNonceLoader 和视频流相关性标识符值，以便频次上限和竞争排除功能正常运行。

接下来，创建 PALNonceLoader 的实例，并为两个委托方法添加桩：

@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 {
}

然后，发起随机数请求，填充其属性，并使用它来初始化随机数管理器：

@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];
}

最后，填充 nonce 加载器委托对象以记录生成的 nonce：

#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);
}

在发出直接 VAST 调用 (DVC) 时，请将您的随机数设置为 givn 参数的值。Nonce 适合包含在网址中，因此您无需对其进行网址编码。

注意： 如果您之前使用 paln 参数提供过 Nonce，我们强烈建议您迁移到 givn 并停止发送 paln。如果同时包含这两个参数，则使用哪个随机数的行为未定义。

最后，您需要添加方法来处理向 SDK 发送内容播放会话信息和点击。请参阅以下示例，了解如何实现方法 sendPlaybackStart、sendPlaybackEnd 和 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];
}

在您的实现中，当首次启动播放时（无论是响应用户启动的操作 [点击播放] 还是应用启动的操作 [自动播放]），都应在“视频播放器启动”时调用 sendPlaybackStart；当播放结束时，应调用 sendPlaybackEnd；每次观看者点击广告时，都应调用 sendAdClick。

（可选）通过第三方广告服务器发送 Google Ad Manager 信号

配置第三方广告服务器向 Ad Manager 发出的请求。完成以下步骤后，随机数参数会从 PAL SDK 传播到您的中介服务器，然后再传播到 Google Ad Manager。这样一来，您就可以通过 Google Ad Manager 更好地创收。

注意： 如果您使用多个第三方解决方案（例如，第三方 SSAI 服务器调用另一个第三方广告服务器），则需要确保将 PAL SDK 的加密随机数转发给每个第三方。

配置第三方广告服务器，以在服务器向 Ad Manager 发出的请求中包含随机数。以下是第三方广告服务器中配置的广告代码示例：

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

如需了解详情，请参阅 Google Ad Manager 服务器端实现指南。

Ad Manager 会查找 givn= 以识别随机数的值。第三方广告服务器需要支持自己的某个宏（例如 %%custom_key_for_google_nonce%%），并将其替换为您在上一步中提供的随机数查询参数。如需详细了解如何实现此目的，请参阅第三方广告服务器的文档。