開始使用

必要條件

Xcode 13 以上版本

本指南說明如何叫用 PAL SDK 接收隨機碼，以及監控播放事件。如要按照完成的指南操作，請下載 PAL tvOS 範例應用程式。

在專案中新增 PAL SDK

使用 Swift Package Manager 安裝 PAL SDK

程式輔助存取權程式庫 SDK 從 2.5.3 版開始支援 Swift Package Manager。請按照下列步驟匯入 Swift 套件。

在 Xcode 中，依序前往「File」(檔案) >「Add Packages...」(新增套件...)，然後安裝 IMA SDK Swift Package。

使用畫面顯示的提示詞框，搜尋「IMA SDK Swift Package GitHub repository」：

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

選取要使用的 PAL SDK Swift Package 版本。如果是新專案，建議選用「Up to Next Major Version」(升級至下一個主要版本)。

完成後，Xcode 會解析套件依附元件，並在背景下載。如要進一步瞭解如何新增套件依附元件，請參閱 Apple 的文章。

手動下載並安裝 PAL SDK

如果不想使用 Swift Package Manager，可以下載 PAL SDK，然後手動新增至專案。

下載並解壓縮 PAL SDK for tvOS
請按照 Apple 開發人員指南，在專案中加入架構。

產生 Nonce

「隨機值」是 PAL 使用 PALNonceLoader 產生的單一加密字串。PAL SDK 要求每個新的串流請求都必須附上新產生的隨機碼。不過，在同一個串流中，隨機碼可重複用於多個廣告請求。

以下所有程式碼片段都是對 PAL tvOS 範例應用程式中 ViewController.m 的修改。

如要要求隨機值，請先匯入 PAL 程式庫：

@import ProgrammaticAccessLibrary;

接著，建立 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 {
}

接著，請發起 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 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];
}

最後，填入隨機碼載入器委派，記錄產生的隨機碼：

#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 可安全用於網址，不需要另外進行編碼。

最後，您需要新增方法，處理將內容播放工作階段資訊和點擊次數傳送至 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 提高營利。

設定第三方廣告伺服器，在伺服器向 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%%)，並將其替換為您在上一個步驟中提供的隨機碼查詢參數。如要進一步瞭解如何完成這項操作，請參閱第三方廣告伺服器的說明文件。