本頁面由 Cloud Translation API 翻譯而成。

開始使用

必要條件

Xcode 13 以上版本。

本指南說明如何叫用 PAL SDK，以便接收 Nonce 並監控播放事件。如要查看使用 PAL 產生 Nonce 的範例應用程式，請從 GitHub 下載 iOS 範例。

將 PAL SDK 新增至專案

使用 Swift Package Manager 安裝 PAL SDK

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

在 Xcode 中依序前往「File」>「Add Packages...」，安裝 IMA SDK Swift 套件。

在出現的提示中，搜尋 IMA SDK Swift 套件 GitHub 存放區：

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

選取要使用的 PAL SDK Swift 套件版本。如果是新專案，建議使用「更新至下一個主要版本」。

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

手動下載並安裝 PAL SDK

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

下載並擷取 iOS 版 PAL SDK
按照 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 查詢參數。如要進一步瞭解如何完成這項作業，請參閱第三方廣告伺服器的說明文件。