翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# クライアント側の広告追跡
AWS Elemental MediaTailor クライアント側の追跡 API を使用すると、広告時間枠中にプレイヤーコントロールをストリーミングワークフローに組み込むことができます。クライアント側の追跡では、プレイヤーまたはクライアントはインプレッションや四分位広告ビーコンなどの追跡イベントを広告決定サーバー (ADS) やその他の広告検証エンティティに発行します。これらのイベントは、全体的な広告時間枠のステータスと、各時間枠内の個々の広告表示の両方を追跡します。インプレッションと四分位数 (ADS) およびその他の広告検証エンティティの詳細については、「」を参照してください。インプレッションと四分位広告ビーコンの詳細については、「」を参照してください[クライアント側のビーコン](ad-reporting-client-side-beaconing.md)。ADS およびその他の広告検証エンティティの詳細については、「」を参照してください[クライアント側の広告追跡統合](ad-reporting-client-side-ad-tracking-integrations.md)。
クライアント側の追跡のためにプレイヤーパラメータとセッションデータを ADS に渡す方法については、[ADS リクエストの MediaTailor プレイヤー変数](variables-player.md)「」および「」を参照してください[ADS リクエストの MediaTailor セッション変数](variables-session.md)。
クライアント側の追跡では、次のような機能が有効になります。
+ 広告ブレークカウントダウンタイマー - 詳細については、「」を参照してください[広告カウントダウンタイマー](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer)。
+ 広告クリックスルー - 詳細については、「」を参照してください[広告クリックスルー](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough)。
+ コンパニオン広告の表示 - 詳細については、「」を参照してください[コンパニオン広告](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads)。
+ スキップ可能な広告 - 詳細については、「」を参照してください[スキップ可能な広告](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads)。
+ プライバシーコンプライアンスの VAST アイコンの表示 - 詳細については、「」を参照してください[Google Why This Ad (WTA) のアイコン](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta)。
+ 広告中のプレイヤースクラブの制御 - 詳細については、「」を参照してください[スクラブ](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing)。
MediaTailor クライアント側の追跡 API を使用すると、クライアント側の追跡に加えて機能を有効にするメタデータを再生デバイスに送信できます。
## クライアント側のレポートワークフロー
次の図は、セッションの初期化から広告の再生とビーコンまでのクライアント側のレポートワークフロー全体を示しています。
クライアント側のレポートワークフローには、次のステップが含まれます。
1. **セッションの初期化** - ビデオプレーヤーは、、オリジントークン`adsParams`、セッション機能などの JSON メタデータを使用して MediaTailor セッションエンドポイントに POST リクエストを送信します。MediaTailor はセッション`trackingUrl`に対して `manifestUrl`と で応答します。
1. **マニフェストリクエストと広告決定** - プレイヤーは MediaTailor にパーソナライズされたマニフェストをリクエストします。MediaTailor は、オリジンから元のコンテンツマニフェストをリクエストし、プレイヤーパラメータを使用して広告決定サーバー (ADS) に広告リクエストを行い、広告メタデータを含む VAST レスポンスを受信し、広告マーカーを含むパーソナライズされたマニフェストをプレイヤーに配信します。
1. **追跡データの取得** - プレイヤーは追跡 URL を定期的にポーリングします (HLS のターゲット期間または DASH の最小更新期間に一致）。MediaTailor は、表示、広告、追跡イベント、ビーコン URLs、広告検証データを含む JSON 追跡メタデータを返します。
1. **広告の再生とビーコン** - 広告ブレーク中に、プレイヤーは追跡メタデータを解析し、広告のレンダリング開始時にインプレッションビーコンを発射し、四分位ビーコン (開始、firstQuartile、中間、thirdQuartile、完了) を適切なタイミングで発射し、必要に応じて広告検証 JavaScript をロードして実行し、表示可能性/検証イベントをサードパーティー検証サービスに送信します。
1. **継続的なポーリング** - プレイヤーはセッション全体で追跡 URL のポーリングを継続し、今後の広告時間枠と動的コンテンツの更新されたメタデータを受け取ります。
このワークフローにより、広告カウントダウンタイマー、クリックスルー機能、コンパニオン広告、スキップ可能な広告、プライバシーコンプライアンスのための VAST アイコン表示などの高度な機能が有効になります。
**Topics**
+ [クライアント側のレポートワークフロー](#ad-reporting-client-side-workflow)
+ [クライアント側の追跡の有効化](#ad-reporting-client-side-enabling)
+ [広告サーバーパラメータ](#ad-reporting-client-side-ad-server-parameters)
+ [オリジンインタラクションクエリパラメータ](#ad-reporting-client-side-origin-interaction-query-parameters)
+ [セッション設定機能](#ad-reporting-client-side-session-configured-features)
+ [クライアント側追跡のベストプラクティス](#ad-reporting-client-side-best-practices)
+ [クライアント側の広告追跡スキーマとプロパティ](ad-reporting-client-side-ad-tracking-schema.md)
+ [広告追跡アクティビティのタイミング](ad-reporting-client-side-ad-tracking-schema-activity-timing.md)
+ [クライアント側の広告追跡のプレイヤーコントロールと機能](ad-reporting-client-side-ad-tracking-schema-player-controls.md)
+ [クライアント側のビーコン](ad-reporting-client-side-beaconing.md)
+ [サーバー側の広告ビーコンを使用したハイブリッドモード](ad-reporting-hybrid-mode.md)
+ [クライアント側の広告追跡統合](ad-reporting-client-side-ad-tracking-integrations.md)
+ [GetTracking を使用した広告ビーコンのページング](#gettracking)
## クライアント側の追跡の有効化
セッションごとにクライアント側の追跡を有効にします。プレイヤーは MediaTailor 設定のセッション初期化プレフィックスエンドポイント`POST`に HTTP を作成します。オプションで、プレイヤーは MediaTailor が広告通話を行ったり、マニフェストのオリジンを呼び出したり、セッションレベルで MediaTailor 機能を呼び出したり無効にしたりするときに使用する追加のメタデータを送信できます。
次の例は、JSON メタデータの構造を示しています。
```
{
"adsParams": { # 'adsParams' is case sensitive
"param1": "value1", # key is not case sensitive
"param2": "value2", # Values can contain spaces. For example, 'value 2' is an allowed value.
},
"origin_access_token":"abc123", # this is an example of a query parameter designated for the origin
"overlayAvails":"on" # 'overlayAvails' is case sensitive. This is an example of a feature that is enabled at the session level.
}
```
MediaTailor コンソールまたは API を使用して、これらのパラメータを参照するように ADS リクエストテンプレート URL を設定します。次の例では、 `player_params.param1`は のプレイヤーパラメータで`param1`、 `player_params.param2`は のプレイヤーパラメータです`param2`。
```
https://my.ads.com/path?{{param1=[player_params.param1]}}&{{param2=[player_params.param2]}}
```
## 広告サーバーパラメータ
JSON 構造の最上位レベルには `adsParams` JSON オブジェクトがあります。このオブジェクト内には、MediaTailor がすべてのセッションリクエストで広告サーバーを読み取って送信できるキーと値のペアがあります。MediaTailor は、次の広告サーバーをサポートしています。
+ Google 広告マネージャー
+ SpringServe
+ FreeWheel
+ Publica
## オリジンインタラクションクエリパラメータ
`adsParams`、、 など、JSON 構造の最上位レベル内の予約されたキーと値のペアは`overlayAvails`、クエリパラメータの形式でオリジンリクエスト URL `availSuppression`に追加されません。MediaTailor がオリジンに対して行うすべてのセッションマニフェストリクエストには、これらのクエリパラメータが含まれます。オリジンは無関係なクエリパラメータを無視します。例えば、MediaTailor はキーと値のペアを使用して、オリジンにアクセストークンを送信できます。
## セッション設定機能
session-initialization JSON 構造を使用して、、`overlayAvails`、 などの MediaTailor 機能を有効、無効に`availSuppression`、または上書きします`adSignaling`。セッションの初期化中に渡された機能設定は、MediaTailor 設定レベルでの設定よりも優先されます。
**注記**
セッションの初期化時に MediaTailor に送信されるメタデータはイミュータブルであり、セッション中は追加のメタデータを追加できません。SCTE-35 マーカーを使用して、セッション中に変化するデータを転送します。詳細については、「[ADS リクエストの MediaTailor セッション変数](variables-session.md)」を参照してください。
**Example : HLS のクライアント側の広告追跡の実行**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8
{
"adsParams": {
"deviceType": "ipad" # This value does not change during the session.
"uid": "abdgfdyei-2283004-ueu"
}
}
```
**Example : DASH のクライアント側の広告追跡を実行する**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.mpd
{
"adsParams": {
"deviceType": "androidmobile",
"uid": "xjhhddli-9189901-uic"
}
}
```
### レポートモードパラメータ
リクエスト本文に `reportingMode`パラメータを含めることで、セッションを初期化するときにレポートモードを指定できます。このパラメータは、MediaTailor がセッションのクライアント側またはサーバー側の広告追跡を実行するかどうかを制御します。
+ `client` - プレイヤーは広告追跡を実行し、ビーコンを広告サーバーに送信します。これは、 が指定されていない場合のデフォルトモード`reportingMode`です。
+ `server` - MediaTailor はサーバー側の広告追跡を実行し、ビーコンを広告サーバーに直接送信します。
**Example サーバー側のレポートモードによるセッションの初期化**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8
{
"adsParams": {
"deviceType": "ipad",
"uid": "abdgfdyei-2283004-ueu"
},
"reportingMode": "server"
}
```
**Example クライアント側のレポートモードによるセッションの初期化 (明示的)**
```
POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.mpd
{
"adsParams": {
"deviceType": "androidmobile",
"uid": "xjhhddli-9189901-uic"
},
"reportingMode": "client"
}
```
**注記**
`reportingMode` パラメータはセッションの初期化時に設定され、セッション中に変更することはできません。`reportingMode` を指定しない場合、MediaTailor は下位互換性を維持するためにデフォルトでクライアント側のレポートになります。
正常なレスポンスは、レスポンス本文`200`を含む HTTP です。本文には、 `manifestUrl`と `trackingUrl`キーを含む JSON オブジェクトが含まれています。値は、プレイヤーが再生と広告イベントの追跡の両方の目的で使用できる相対 URLs です。
```
{
"manifestUrl": "/v1/{{dash}}{{master}}/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8?aws.sessionId={{session-id}}",
"trackingUrl": "/v1/tracking/{{hashed-account-id}}/{{origin-id}}/{{session-id}}"
}
```
クライアント側の追跡スキーマの詳細については、「」を参照してください[クライアント側の広告追跡スキーマとプロパティ](ad-reporting-client-side-ad-tracking-schema.md)。
## クライアント側追跡のベストプラクティス
このセクションでは、ライブワークフローと VOD ワークフローの両方で MediaTailor でクライアント側を追跡するためのベストプラクティスの概要を説明します。
### ライブワークフロー
最新の広告追跡メタデータを常に取得するために、HLS の各ターゲット期間、または DASH の最小更新期間に一致する間隔で追跡エンドポイントをポーリングします。この間隔を一致させることは、クリエイティブにインタラクティブコンポーネントまたはオーバーレイコンポーネントがあるワークフローで特に重要です。
**注記**
一部のプレイヤーは、ポーリングの代替として使用できるイベントリスナーをサポートしています。例えば、MediaTailor 広告 ID デコレーション機能はセッションごとに有効にする必要があります。詳細については、「[広告 ID デコレーション](ad-id-decoration.md)」を参照してください。この機能を使用すると、表示の各広告に日付範囲 (HLS) またはイベント要素 (DASH) 識別子が配置されます。プレイヤーは、これらのマニフェストタグを、セッションの MediaTailor 追跡エンドポイントを呼び出すプロンプトとして使用できます。
### VOD ワークフロー
セッションの初期化に成功し、MediaTailor がメディアを含む最初のマニフェストを受け取ったら、追跡エンドポイントを一度呼び出すだけで済みます。
### サーバーガイド広告挿入
サーバーガイド広告挿入 (SGAI) セッションは `GetTracking` API を使用しません。代わりに、 を使用すると`aws.reportingMode=CLIENT`、MediaTailor は、プレイヤーが広告コンテンツをリクエストしたときに、各アセットリストレスポンスの `TRACKING`セクションに追跡情報を提供します。セッション初期化レスポンスには は含まれません`trackingUrl`。
クライアント側で追跡される SGAI セッションのアセットリストレスポンスの構造は次のとおりです。
```
{
"ASSETS": [
{ "DURATION": 20.0, "URI": "https://cdn.example.com/ad1/master.m3u8" },
{ "DURATION": 10.0, "URI": "https://cdn.example.com/ad2/master.m3u8" }
],
"TRACKING": {
...VAST tracking events and beacon URLs for each ad...
}
}
```
SGAI メソッドのクライアント側追跡を実装する場合:
+ を呼び出すのではなく、アセットリストレスポンスから `TRACKING`セクションを解析する `GetTracking`
+ 広告イベントレポートのアセットリストで提供されている追跡 URLs を使用する
+ プレイヤーの実際の広告再生イベントに基づく射撃追跡ビーコン
+ アセットリストが取得されるたびに、各広告時間枠の追跡を個別に処理する
**重要**
`TRACKING` セクションは、 が設定されている場合にのみアセットリストに含まれ`aws.reportingMode=CLIENT`ます。サーバー側のレポートを使用する場合 (SGAI のデフォルト）、MediaTailor は `TRACKING`セクションを省略し、代わりにビーコンデータを広告 URIs。詳細については、「[サーバーガイド広告挿入によるサーバー側の追跡 (SGAI)](ad-reporting-server-side-sgai.md)」を参照してください。
## GetTracking を使用した広告ビーコンのページング
`GetTracking` エンドポイントを使用して、プレイヤーに返される広告の数を絞り込みます。例えば、マニフェストウィンドウが広く、長時間にわたる場合、返される広告ビーコンの数はプレイヤーのパフォーマンスに影響を与える可能性があります。
`GetTracking` は、返されたビーコンのリストをページングすることで、返されたビーコンの数を絞り込むために使用できる`NextToken`値を返します。`NextToken` 値を循環して、広告ビーコンの `StartTimeInSeconds`フィールドの目的の値を見つけることができます。
+ への最初の呼び出しでは`GetTracking`、マニフェストウィンドウに含まれる可能性のあるすべての広告が返されます。これには、それぞれの `NextToken`および の値が含まれます。
+ `GetTracking` リクエストに が含まれ*ていない場合*`NextToken`、マニフェストウィンドウ内のすべての広告が返されます。
+ `GetTracking` リクエストに が含まれている`NextToken`が、返す新しいビーコンがない場合、MediaTailor は元のリクエストで送信`NextToken`した と同じ値を返します。
+ 広告に対応するビーコンがなくなると、 はレスポンスから広告`GetTracking`を削除します。
+ からのトークンは 24 時間後に`GetTracking`期限切れになります。`NextToken` 値が 24 時間以上経過している場合、 への次の呼び出しは null 値 `GetTracking`を返します`NextToken`。
### プレイヤーからの GetTracking の一般的な呼び出しシーケンス
クライアントプレイヤーからの`GetTracking`リクエストは、トークンに関連する `NextToken`および 広告とビーコンを含むリクエスト本文を含む POST です。
```
https://YouMediaTailorUrl/v1/tracking
{
"NextToken": "value"
.
.
.
}
```
`GetTracking` で を使用する一般的な順序`NextToken`は次のとおりです。
1. を最初に呼び出します`GetTracking`。
すべての広告とビーコン、および後続の呼び出し`NextToken`の最初の が返されます。
1. の値が null の場合、MediaTailor `NextToken`はすべての広告ビーコンを返します。
1. の有効期限が切れている場合、MediaTailor `NextToken`は HTTP リターンコード 400 エラーメッセージを返します。
新しい を呼び出し`GetTracking`て、有効な を取得します`NextToken`。
1. レスポンス全体をスキャンして、目的の範囲内にある広告ビーコン`StartTimeInSeconds`の を見つけます。
1. 目的の `NextToken`に関連付けられた の値`GetTracking`を使用して、 に新しい呼び出しを行います`StartTimeInSeconds`。
1. 必要に応じて、再生したい広告が見つかるまで、返された広告をもう一度繰り返します。
#### 拡張例
この例では、 `GetTracking`の `NextToken` を使用して、プレイヤーに返される広告ビーコンの数を制限する方法を示します。
MediaTailor は`GetTracking`リクエストを受け取ります。レスポンスには、ID 9935407 の広告と`StartTimeInSeconds`、値 52.286 秒と 48.332 秒の 2 つのビーコンが含まれています。
MediaTailor は、`NextToken`次のように で JSON レスポンスを送信します。
```
{
"NextToken": JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb
"avails": [
{
"ads": [
{
"adId": "9935407",
"adVerifications": [],
"companionAds": [],
"creativeId": "",
"creativeSequence": "",
"duration": "PT15S",
"durationInSeconds": 15,
"extensions": [],
"mediaFiles": {
"mediaFilesList": [],
"mezzanine": ""
},
"startTime": "PT30S",
"StartTimeInSeconds": 45,
"trackingEvents": [
{
"beaconUrls": [
"http://adserver.com/tracking?event=Impression "
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "9935414",
"eventType": "secondQuartile",
"startTime": "PT52.286S",
"StartTimeInSeconds": 52.286
},
{
"beaconUrls": [
"http://adserver.com/tracking?event=firstQuartile"
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "9935412",
"eventType": "firstQuartile",
"startTime": "PT48.332S",
"StartTimeInSeconds": 48.332
}
],
"vastAdId": ""
}
],
"startTime": "PT46.47S",
"StartTimeInSeconds": 46.47
}
]
}
```
次の`GetTracking`リクエストでは、MediaTailor は JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb `NextToken`という値で応答します。
MediaTailor は、前の呼び出し`NextToken`の で設定された `StartTimeInSeconds` に一致する広告とビーコンで応答します。
レスポンスに、ID 9235407 の以前の広告に加えて、ID 9935407 の別の広告が含まれているとします。広告 ID 9235407 のビーコンには、`StartTimeInSeconds`s 132.41 と 70.339 があります。
MediaTailor はセッション内のすべてのビーコンを繰り返して、ID 9235407 の広告からビーコン 3 とビーコン 4 である 52.286 秒`StartTimeInSeconds`を超えるビーコンを選択します。
```
{
"NextToken": ZkfknvbfsdgfbsDFRdffg12EdffecFRvhjyjfhdfhnjtsg5SDGN
"avails": [
{
"ads": [
{
"adId": "9235407",
"adVerifications": [],
"companionAds": [],
"creativeId": "",
"creativeSequence": "",
"duration": "PT15.816S",
"durationInSeconds": 19.716,
"extensions": [],
"mediaFiles": {
"mediaFilesList": [],
"mezzanine": ""
},
"startTime": "PT2M0S",
"StartTimeInSeconds": 120.0,
"trackingEvents": [
{
"beaconUrls": [
"http://adserver.com/tracking?event=complete"
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "8935414",
"eventType": "firstQuartile",
"startTime": "PT1M10.330S",
"StartTimeInSeconds": 70.339
},
{
"beaconUrls": [
"http://adserver.com/tracking?event=thirdQuartile"
],
"duration": "PT0S",
"durationInSeconds": 0,
"eventId": "8935412",
"eventType": "secondQuartile",
"startTime": "PT2M12.41S",
"StartTimeInSeconds": 132.41
}
],
"vastAdId": ""
},
],
"startTime": "PT36.47S",
"StartTimeInSeconds": 36.47
}
]
}
```