開始する

前提条件

Xcode 13 以降

このガイドでは、PAL SDK を呼び出してノンスを受け取り、再生イベントをモニタリングする方法について説明します。完成したガイドに沿って操作するには、PAL tvOS サンプルアプリケーションをダウンロードします。

プロジェクトに PAL SDK を追加する

Swift Package Manager を使用して PAL SDK をインストールする

Programmatic Access Library 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-tvos
```
使用する PAL SDK の Swift パッケージのバージョンを選択します。新しいプロジェクトの場合は [Up to Next Major Version] を選択することをおすすめします。

完了すると、Xcode はパッケージの依存関係を解決し、バックグラウンドでダウンロードします。パッケージの依存関係の追加について詳しくは、Apple の記事を参照してください。

PAL SDK を手動でダウンロードしてインストールする

Swift Package Manager を使用しない場合は、PAL SDK をダウンロードして、プロジェクトに手動で追加できます。

tvOS 用 PAL SDK をダウンロードして解凍します。
Apple デベロッパーガイドに沿って、フレームワークをプロジェクトに組み込みます。

ノンスを生成する

「ノンス」とは、PALNonceLoader を使用して PAL によって生成される 1 つの暗号化された文字列です。PAL SDK では、新しいストリームリクエストごとに、新たに生成されたノンスを付加する必要があります。ただし、同じストリーム内の複数の広告リクエストでノンスを再利用できます。

以下のコードスニペットはすべて、PAL tvOS サンプルアプリケーションの ViewController.m の変更です。

ノンスをリクエストするには、まず PAL ライブラリをインポートします。

@import ProgrammaticAccessLibrary;

注: アプリに複数のページまたは同等の構造がない限り、アプリのユーザーセッションごとに PALNonceLoader クラスのインスタンスを 1 つだけ作成することをおすすめします。これにより、ページまたはアプリのユーザーセッションのライフサイクル全体にわたって、ページ相関子（&correlator パラメータ）が変更されなくなります。

ストリームコリレーター（&scor）は引き続き制御できます。これは、新しいストリームごとに 1 回リセットする必要があります。フリークエンシーキャップと競合相手の除外機能が正しく動作するように、同じストリームのすべての広告リクエストで同じ PALNonceLoader とストリームの correlator 値を共有する必要があります。

次に、PALNonceLoader のインスタンスを作成し、2 つのデリゲートメソッドのスタブを追加します。

@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 パラメータの値としてノンスを設定します。ノンスの URL はそのまま指定でき、URL エンコードは必要ありません。

最後に、コンテンツ再生セッション情報とクリックを 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 アドマネージャーのシグナルを送信する

アドマネージャーに対するサードパーティ広告サーバーのリクエストを設定します。次の手順を完了すると、nonce パラメータが PAL SDK から仲介サーバーを経由して Google アドマネージャーに伝播されます。これにより、Google アドマネージャーを通じて収益化を向上させることができます。

アドマネージャーへのサーバーのリクエストに nonce を含めるように、第三者広告サーバーを設定します。第三者広告サーバー内で設定された広告タグの例を次に示します。

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

詳しくは、Google アドマネージャーのサーバーサイド実装ガイドをご覧ください。

アドマネージャーは givn= を探して、ノンス値を特定します。第三者広告サーバーは、%%custom_key_for_google_nonce%% などの独自のいくつかのマクロをサポートし、前のステップで指定した nonce クエリパラメータに置き換える必要があります。この方法について詳しくは、第三者広告サーバーのドキュメントをご覧ください。