开始使用

前提条件

• Xcode 13 或更高版本

本指南介绍了如何调用 PAL SDK 来接收 Nonce 并监控 播放事件。要按照完整指南进行操作，请下载 PAL tvOS 示例应用。

将 PAL SDK 添加到您的项目中

使用 Swift Package Manager 安装 PAL SDK

Programmatic Access Library SDK 支持 Swift Package Manager 版本。按照 导入 Swift 软件包的步骤。

1. 在 Xcode 中，前往 文件 >添加软件包...。

2. 在显示的提示中，搜索 IMA SDK Swift Package 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 iOS
2. 请按照 Apple 开发者指南将该框架整合到您的项目中。

生成 Nonce

“Nonce”是由 PAL 使用 PALNonceLoader。PAL SDK 要求附带每个新的视频流请求 由新生成的 Nonce 生成。不过，Nonce 可以重复用于多个广告 请求数量。

下面的所有代码段均经过修改 ViewController.m在 PAL tvOS 示例应用。

如需请求 Nonce，请先导入 PAL 库：

@import ProgrammaticAccessLibrary;

注意： 我们建议您仅创建 PALNonceLoader 类，除非您的应用具有 多个网页或等效结构。这样可保持网页的 Correlator &correlator 参数，在网页或用户的生命周期内保持不变 会话

您仍然可以控制视频流 Correlator（即 &scor），它应该 每次进行新的直播时都会重置一次同一视频流的所有广告请求都应共享 相同的 PALNonceLoader 和视频流 Correlator 值可用于频次上限和 竞争排除功能正常运行。

接下来，创建 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 '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 {
}

然后，启动一个 Nonce 请求，填充其属性，并将其用于 初始化 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 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];
}

最后，填充 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) 时，请将 Nonce 的值设为 givn 参数。Nonce 具有网址安全性，您无需对其进行网址编码。

注意： 如果您之前使用 paln 参数提供了一个 Nonce，它将被 强烈建议迁移到 givn 并停止发送 paln。如果两者 参数，那么这是关于哪个 Nonce 的未定义行为

最后，您需要添加用于处理内容播放会话的发送方法 信息和点击传递给 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 发出的请求。在您之后 完成以下步骤后，Nonce 参数将从 PAL SDK 传播， 然后将数据传输到 Google Ad Manager这样一来， 通过 Google Ad Manager 获得更高收益

注意 ：如果您使用多个第三方解决方案，例如第三方 SSAI 服务器调用其他第三方广告服务器时，您需要确保 PAL SDK 的加密 Nonce 会转发给每个第三方。

配置您的第三方广告服务器，以在该服务器的 向 Ad Manager 发送广告请求下面是在 第三方广告服务器：

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

有关详情，请参阅 Google Ad Manager 服务器端实施 指南。

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