このページは Cloud Translation API によって翻訳されました。

開始する

前提条件

Xcode 13 以降。

このガイドでは、PAL SDK を呼び出してノンスを受信し、再生イベントをモニタリングする方法について説明します。PAL を使用してノンスを生成するサンプルアプリを確認するには、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 パッケージのバージョンを選択します。新しいプロジェクトには、[Up to Next Major Version] を使用することをおすすめします。

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

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

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

PAL SDK for iOS をダウンロードして解凍します。
Apple Developer Guide の手順に沿って、プロジェクトにフレームワークを組み込みます。

ノンスを生成する

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

以下のコードスニペットはすべて、PAL iOS サンプルアプリの ViewController.m を変更したものです。

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

@import ProgrammaticAccessLibrary;

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

次に、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 '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 {
}

次に、ノンスリクエストを開始し、そのプロパティを設定し、それを使用してノンスマネージャーを初期化します。

@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];
}

最後に、ノンスローダーのデリゲートに、生成されたノンスをログに記録します。

#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];
}

実装では、ユーザーが開始したアクション（Click-to-Play）またはアプリが開始したアクション（自動再生）に応じて、初めて再生が開始されるときに「動画プレーヤーの起動」時に sendPlaybackStart を呼び出します。また、再生が終了したときに sendPlaybackEnd を呼び出し、視聴者が広告をクリックするたびに sendAdClick を呼び出す必要があります。

（省略可）第三者広告サーバー経由で Google アドマネージャーシグナルを送信する

アドマネージャーに対する第三者広告サーバーのリクエストを設定します。以下の手順を完了すると、ノンスパラメータは PAL SDK から中継サーバーを経由して Google アドマネージャーに伝播されます。これにより、Google アドマネージャーでの収益化を強化できます。

アドマネージャーに対するサーバーリクエストにノンスを含めるように、第三者広告サーバーを設定します。第三者広告サーバー内に広告タグを設定している例を次に示します。

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

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

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