开始使用

前提条件

  • Xcode 13 或更高版本。

本指南介绍了如何调用 PAL SDK 以接收 Nonce 并监控播放事件。如需查看使用 PAL 生成 Nonce 的示例应用，请从 GitHub 下载 iOS 示例。

将 PAL SDK 添加到您的项目中

使用 Swift Package Manager 安装 PAL SDK

从 2.5.3 版开始，Programmatic Access Library SDK 支持 Swift Package Manager。请按照以下步骤导入 Swift 软件包。

  1. 在 Xcode 中，依次点击 File（文件）> Add Packages...（添加软件包...），以安装 IMA SDK Swift Package。

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

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

  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 可以重复用于同一数据流中的多个广告请求。

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

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

@import ProgrammaticAccessLibrary;

您仍然可以控制数据流 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 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;
  request.OMIDPartnerName = @"SamplePartner";
  request.OMIDPartnerVersion = @"6.2.1";
  request.OMIDVersion = @"1.2.3";

  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 是网址安全的，您无需对其进行网址编码。

最后，您需要添加一些方法来处理向 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 提升变现能力。

配置您的第三方广告服务器，以在服务器向 Ad Manager 发出的请求中添加 Nonce。以下是在第三方广告服务器内配置的广告代码的示例：

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 查询参数。如需详细了解如何实现此操作，请参阅第三方广告服务器的文档。