Dynamic Ad Insertion API を使用すると、DAI ライブ配信をリクエストしてトラッキングできます。
サービス: dai.google.com
すべての URI は https://dai.google.com
を基準とします。
メソッド: ストリーム
メソッド | |
---|---|
stream |
POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream
DAI DAI Pod Serving ライブ配信セッションを登録します。 |
HTTP リクエスト
POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream
パスパラメータ
パラメータ | |
---|---|
network_code |
string
パブリッシャーの Google アド マネージャー ネットワークのコード。 |
custom_asset_key |
string
Google アド マネージャーでこのイベントに関連付けられたカスタム ID。 |
リクエスト本文
リクエスト本文のタイプは application/x-www-form-urlencoded
で、次のパラメータが含まれています。
パラメータ | ||
---|---|---|
アド マネージャー ターゲティング パラメータ | 省略可 | 追加のターゲティング パラメータ。 |
ストリーム パラメータをオーバーライドする | 省略可 | ストリーム作成パラメータのデフォルト値をオーバーライドします。 |
HMAC 認証 | 省略可 | HMAC ベースのトークンを使用して認証します。 |
レスポンスの本文
成功した場合、レスポンスの本文には新しい Stream
オブジェクトが含まれます。
Open Measurement
DAI API の Verifications
フィールドには、Open Measurement の確認に関する情報が含まれます。このフィールドには、クリエイティブの再生を確認するためにサードパーティの測定コードを実行するために必要なリソースとメタデータを一覧表示する 1 つ以上の Verification
要素が含まれます。JavaScriptResource
のみがサポートされています。詳しくは、IAB Tech Lab と VAST 4.1 の仕様をご覧ください。
メソッド: Pod セグメント
メソッド | |
---|---|
pod segment |
GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}
指定されたイベント ID の DAI ストリームを作成します。 |
HTTP リクエスト
GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}
パスパラメータ
パラメータ | |
---|---|
network_code |
string
パブリッシャーの Google アド マネージャー ネットワークのコード。 |
custom_asset_key |
string
Google アド マネージャーでこのイベントに関連付けられているカスタム識別子。 |
pod_identifier |
次の形式がサポートされています。 pod/{integer}
現在のミッドロール挿入点の数値 ID。連続配信広告 ID は、広告ブレーク イベントごとに、 ad_break_id/{string}
現在のミッドロール挿入点の文字列 ID。 |
profile_name |
string
リクエストされた Google アド マネージャー DAI エンコード プロファイルの名前。エンコード プロファイルは、選択したイベント用に構成されたエンコード プロファイルのいずれかである必要があります。 |
segment_number |
integer
現在の広告連続配信内のリクエストされたセグメントのインデックス(0 から始まる)。 |
segment_format |
string
リクエストされたセグメント形式に関連付けられたファイル拡張子。使用できる拡張機能は |
クエリ パラメータ
パラメータ | ||||||
---|---|---|---|---|---|---|
stream_id |
必須 |
string
現在のユーザーのセッションのストリーム ID。この値は、 |
||||
sd |
required1
|
integer
リクエストされたセグメントの長さ(ミリ秒単位)。 |
||||
so |
省略可 |
連続配信広告内のリクエストされたセグメントのオフセット(ミリ秒単位)。 |
||||
pd |
必須2 |
integer
連続配信広告の再生時間(ミリ秒単位)。 |
||||
auth-token |
必須 |
string
現在の広告連続配信の署名付き URL エンコード HMAC トークン。 |
||||
last |
省略可 |
boolean
広告ブレーク内の最後のセグメントを示します。他のすべてのセグメントでは、このパラメータを省略します。 |
||||
scte35 |
省略可 |
string
この広告ブレークの Base64 でエンコードされた SCTE-35 シグナル。 |
||||
cust_params |
省略可 |
string
アド マネージャー キャンペーンのターゲティングに使用される Key-Value ペアのセット。これらのペアは、URL エンコードされたクエリ文字列として表す必要があります。 例:
|
脚注
例
GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST
GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST
レスポンスの本文
成功すると、レスポンスの本文は、リクエストで指定された形式とパラメータに一致する再生可能なストリーム セグメントになります。
方法: HLS Pod マニフェスト
クライアントの動画プレーヤーが読み込んで再生する準備ができているライブ配信の HLS 連続配信広告マニフェストを取得します。
メソッド | |
---|---|
GET |
GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/pod/{pod_id}.m3u8;
広告連続配信の HLS マルチバリエーション再生リストを取得する API。 |
HTTP リクエスト
GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}
パスパラメータ
パラメータ | |
---|---|
network_code |
string
パブリッシャーの Google アド マネージャー ネットワークのコード。 |
custom_asset_key |
string
Google アド マネージャーでこのイベントに関連付けられているカスタム識別子 |
pod_id |
integer
現在のミッドロール挿入点の数値 ID。広告連続配信 ID は、広告ブレーク イベントごとに |
クエリ パラメータ
パラメータ | ||||||
---|---|---|---|---|---|---|
stream_id |
必須 |
string
現在のユーザーのセッションのストリーム ID。この値は、 |
||||
pd |
必須 |
integer
連続配信広告の再生時間(ミリ秒単位)。 |
||||
scte35 |
省略可 |
string
この広告ブレークの Base64 でエンコードされた SCTE-35 シグナル。 |
||||
cust_params |
省略可 |
string
アド マネージャー キャンペーンのターゲティングに使用される Key-Value ペアのセット。これらのペアは、URL エンコードされたクエリ文字列として表す必要があります。 例:
|
レスポンスの本文
成功すると、レスポンスの本文は HLS マルチバリアント プレイリストになります。
方法: DASH Pod マニフェスト
クライアントの動画プレーヤーが読み込んで再生する準備ができているライブ配信の MPEG-DASH 連続配信広告マニフェストを取得します。
メソッド | |
---|---|
GET |
GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd
広告連続配信の MPEG-DASH mpd 再生リストを取得する API。 |
HTTP リクエスト
GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}
パスパラメータ
パラメータ | |
---|---|
network_code |
string
パブリッシャーの Google アド マネージャー ネットワークのコード。 |
custom_asset_key |
string
Google アド マネージャーでこのイベントに関連付けられているカスタム識別子 |
stream_id |
string
現在のユーザーのセッションのストリーム ID。この値は、 |
pod_id |
integer
現在のミッドロール挿入点の数値識別子。連続配信広告 ID は、広告ブレーク イベントごとに、 |
クエリ パラメータ
パラメータ | ||||||
---|---|---|---|---|---|---|
pd |
必須 |
integer
連続配信広告の再生時間(ミリ秒単位)。 |
||||
scte35 |
省略可 |
string
この広告ブレークの Base64 でエンコードされた SCTE-35 シグナル。 |
||||
cust_params |
省略可 |
string
アド マネージャー キャンペーンのターゲティングに使用される Key-Value ペアのセット。これらのペアは、URL エンコードされたクエリ文字列として表す必要があります。 例:
|
レスポンスの本文
成功した場合、レスポンスの本文は MPEG-DASH mpd プレイリストです。
方法: DASH Pod 期間テンプレート
メソッド | |
---|---|
pods |
GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json
Google アド マネージャーから DASH 期間テンプレートをリクエストします。このテンプレートには、ストリーム パラメータで入力する必要があるマクロが含まれています。これらのマクロが入力されると、テンプレートはミッドロール挿入点となり、DASH マニフェストに縫い付けることができます。 |
HTTP リクエスト
GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json
パスパラメータ
パラメータ | |
---|---|
network_code |
string
パブリッシャーの Google アド マネージャー ネットワークのコード。 |
custom_asset_key |
string
Google アド マネージャーでこのイベントに関連付けられているカスタム識別子。 |
クエリ パラメータ
パラメータ | ||
---|---|---|
stream_id |
必須 |
string
現在のユーザーのセッションのストリーム ID。この値は、 |
レスポンスの本文
成功した場合、レスポンスの本文には新しい PodTemplateResponse
オブジェクトが含まれます。
方法: メディアによるオーナー確認
再生中に広告メディア ID が検出されたら、上記の stream エンドポイントから取得した media_verification_url を使用してすぐにリクエストを送信します。これらのリクエストは、サーバーがメディアの検証を開始するサーバーサイド ビーコン ストリームでは必要ありません。
media verification
エンドポイントへのリクエストはべき等です。
メソッド | |
---|---|
media verification |
GET /{media_verification_url}/{ad_media_id}
メディアの検証イベントを API に通知します。 |
HTTP リクエスト
GET https://{media-verification-url}/{ad-media-id}
レスポンスの本文
media verification
は次のレスポンスを返します。
- メディアの検証が成功し、すべての ping が送信された場合は
HTTP/1.1 204 No Content
。 HTTP/1.1 404 Not Found
: URL の形式が正しくないか、有効期限が切れているためにリクエストでメディアを検証できない場合。- この ID の以前の確認リクエストが成功した場合は
HTTP/1.1 404 Not Found
。 HTTP/1.1 409 Conflict
: この時点で別のリクエストがすでに ping を送信している場合。
広告メディア ID
広告メディア ID は、個別のメタデータ トラック(HLS トランスポート ストリームの場合はタイミング付きメタデータ、MP4 ファイルの場合は emsg)にエンコードされます。広告メディア ID は常に文字列 google_
で始まります。
各広告確認リクエストを行う前に、メタデータ エントリのテキスト コンテンツ全体を広告確認 URL に追加する必要があります。
メソッド: metadata
metadata_url
のメタデータ エンドポイントは、広告 UI の作成に使用される情報を返します。メタデータ エンドポイントは、サーバーサイド ビーコン ストリームでは使用できません。このストリームでは、サーバーが広告メディアの検証を開始します。
メソッド | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
広告メタデータ情報を取得します。 |
HTTP リクエスト
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
レスポンスの本文
成功した場合、レスポンスは PodMetadata
のインスタンスを返します。
メタデータの解析
メタデータには、tags
、ads
、広告 breaks
の 3 つの個別のセクションがあります。データのエントリ ポイントは tags
セクションです。そこからタグを反復処理し、動画ストリームで見つかった広告メディア ID の接頭辞が名前の最初のエントリを見つけます。たとえば、次のような広告メディア ID があるとします。
google_1234567890
次に、google_12345
という名前のタグ オブジェクトを見つけます。この場合、広告メディア ID と一致します。適切な広告メディア接頭辞オブジェクトを見つけたら、広告 ID、ミッドロール挿入点 ID、イベントタイプを検索できます。広告 ID は ads
オブジェクトのインデックス登録に使用され、広告ブレーク ID は breaks
オブジェクトのインデックス登録に使用されます。
Response data
ストリーム
Stream は、新しく作成されたストリームのリソースリストを JSON 形式でレンダリングするために使用されます。JSON 表現 |
---|
{ "stream_id": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "heartbeat_url": string, "polling_frequency": number, "pod_manifest_url": string, "manifest_format": string, } |
フィールド | |
---|---|
stream_id |
string GAM ストリーム ID。 |
media_verification_url |
string 再生イベントのトラッキング用ベースエンドポイントとして使用されるメディア検証 URL。 |
metadata_url |
string 今後のストリーミング広告イベントに関する定期的な情報をポーリングするために使用されるメタデータ URL。 |
session_update_url |
string このストリームのターゲティング パラメータの更新に使用されるセッションの更新 URL。 ターゲティング パラメータの元の値は、最初のストリーム作成リクエストで取得されます。 |
heartbeat_url |
string サーバーサイドのビーコン ストリームを稼働させるために使用されるハートビート URL。{PollingFrequency} 秒ごとに ping する必要があります。 サーバーサイド ビーコン処理ストリーム用に入力されます。 |
polling_frequency |
number metadata_url または heartbeat_url をリクエストする際のポーリング頻度(秒単位)。 |
pod_manifest_url |
string 連続広告配信マニフェスト URL テンプレートは、HLS のマルチバリアント プレイリストの URL または DASH の MPD に対応する、ストリームの連続広告配信マニフェストを取得する URL の生成に使用されます。ダイナミック広告挿入タイプ POD_SERVING_MANIFEST のライブ配信イベントに入力されます。 https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType |
manifest_format |
string マニフェストの形式は、pod_manifest_url から取得したマニフェストの形式です(ダッシュまたは hls)。 |
PodMetadata
PodMetadata には、広告、ミッドロール挿入点、メディア ID タグに関するメタデータ情報が含まれます。JSON 表現 |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
フィールド | |
---|---|
tags |
map[string, object(TagSegment)] タグ接頭辞でインデックス登録されたタグセグメントのマップ。 |
ads |
map[string, object(Ad)] 広告 ID でインデックスされた広告のマップ。 |
ad_breaks |
map[string, object(AdBreak)] 広告ブレーク ID でインデックスされた広告ブレークのマップ。 |
TagSegment
TagSegment には、広告、そのミッドロール挿入点、イベントタイプへの参照が含まれます。type="progress" の TagSegment は、広告メディアの検証エンドポイントに ping しないでください。JSON 表現 |
---|
{ "ad": string, "ad_break_id": string, "type": string, } |
フィールド | |
---|---|
ad |
string このタグの広告の ID。 |
ad_break_id |
string このタグの広告ブレークの ID。 |
type |
string このタグのイベントタイプ。 |
AdBreak
AdBreak は、ストリーム内の 1 つのミッドロール挿入点を表します。長さ、タイプ(ミッドロール / プレロール / ポストロール)、広告数を指定します。JSON 表現 |
---|
{ "type": string, "duration": number, "expected_duration": number, "ads": number, } |
フィールド | |
---|---|
type |
string 有効な休憩タイプは、pre、mid、post です。 |
duration |
number このミッドロール挿入点の広告の合計時間(秒単位)。 |
expected_duration |
number すべての広告とスレートを含む、想定される広告ブレークの長さ(秒単位)。 |
ads |
number ミッドロール挿入点内の広告の数。 |
広告
Ad は、ストリーム内の広告を表します。JSON 表現 |
---|
{ "ad_break_id": string, "position": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
フィールド | |
---|---|
ad_break_id |
string この広告のミッドロール挿入点の ID。 |
position |
number ミッドロール挿入点におけるこの広告の位置(1 から始まります)。 |
duration |
number 広告の長さ(秒単位)。 |
title |
string 広告のタイトル(省略可)。 |
description |
string 広告の説明(省略可)。 |
advertiser |
string 広告主 ID(省略可)。 |
ad_system |
string オプションの広告システム。 |
ad_id |
string オプションの広告 ID。 |
creative_id |
string クリエイティブ ID(省略可)。 |
creative_ad_id |
string オプションのクリエイティブ広告 ID。 |
deal_id |
string 省略可能な取引 ID。 |
clickthrough_url |
string (省略可)リンク先 URL。 |
click_tracking_urls |
string クリック トラッキング URL(省略可)。 |
verifications |
[object(Verification)] サードパーティの測定コードを実行してクリエイティブの再生を検証するために必要なリソースとメタデータを一覧表示する、Open Measurement の検証エントリ(省略可)。 |
slate |
boolean 現在のエントリがスレートであることを示すブール値(省略可) |
icons |
[object(Icon)] アイコンのリスト(空の場合は省略)。 |
wrappers |
[object(Wrapper)] ラッパーのリスト。空の場合は省略されます。 |
universal_ad_id |
object(UniversalAdID) オプションのユニバーサル広告 ID。 |
extensions |
string VAST 内のすべての <Extension> ノードのリスト(省略可)。 |
companions |
[object(Companion)] この広告と一緒に表示できるオプションのコンパニオンです。 |
interactive_file |
object(InteractiveFile) 広告の再生中に表示するオプションのインタラクティブ クリエイティブ(SIMID)。 |
PodTemplateResponse
PodTemplateResponse は、Pod のステッチング用に VTP に返される JSON ペイロードを表します。JSON 表現 |
---|
{ "dash_period_template": string, "segment_duration_ms": int64, } |
フィールド | |
---|---|
dash_period_template |
string DashPeriodTemplate は、合成前に適切なデータが入力される期間の XML テンプレートです。 |
segment_duration_ms |
int64 SegmentDurationMS は、期間セグメントの長さ(ミリ秒単位)です。 |
アイコン
Icon には、VAST アイコンに関する情報が含まれます。JSON 表現 |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
フィールド | |
---|---|
click_data |
object(ClickData) |
creative_type |
string |
click_fallback_images |
[object(FallbackImage)] |
height |
int32 |
width |
int32 |
resource |
string |
type |
string |
x_position |
string |
y_position |
string |
program |
string |
alt_text |
string |
ClickData
ClickData には、アイコンのクリックスルーに関する情報が含まれます。JSON 表現 |
---|
{ "url": string, } |
フィールド | |
---|---|
url |
string |
FallbackImage
FallbackImage には、VAST の代替画像に関する情報が含まれます。JSON 表現 |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
フィールド | |
---|---|
creative_type |
string |
height |
int32 |
width |
int32 |
resource |
string |
alt_text |
string |
ラッパー
Wrapper には、ラッパー広告に関する情報が含まれます。取引 ID が存在しない場合、取引 ID は含まれません。JSON 表現 |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
フィールド | |
---|---|
system |
string 広告システムの ID。 |
ad_id |
string ラッパー広告に使用される広告 ID。 |
creative_id |
string ラッパー広告に使用されるクリエイティブ ID。 |
creative_ad_id |
string ラッパー広告に使用されるクリエイティブ広告 ID。 |
deal_id |
string ラッパ―広告の取引 ID(省略可)。 |
確認
ベリフィケーションでは Open Measurement に関する情報が含まれ、第三者の視認性および検証測定を容易にします。現在サポートされているのは JavaScript リソースのみです。https://iabtechlab.com/standards/open-measurement-sdk/ をご覧ください。JSON 表現 |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
フィールド | |
---|---|
vendor |
string 検証ベンダー。 |
java_script_resources |
[object(JavaScriptResource)] 検証用の JavaScript リソースのリスト。 |
tracking_events |
[object(TrackingEvent)] オーナー確認のトラッキング イベントのリスト。 |
parameters |
string ブートストラップ確認コードに渡される不透明な文字列。 |
JavaScriptResource
JavaScriptResource には、JavaScript による検証に関する情報が含まれます。JSON 表現 |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
フィールド | |
---|---|
script_url |
string JavaScript ペイロードの URI。 |
api_framework |
string APIFramework は、確認コードを実行する動画フレームワークの名前です。 |
browser_optional |
boolean このスクリプトをブラウザの外部で実行できるかどうか。 |
TrackingEvent
TrackingEvent には、特定の状況でクライアントが ping する必要がある URL が含まれます。JSON 表現 |
---|
{ "event": string, "uri": string, } |
フィールド | |
---|---|
event |
string トラッキング イベントのタイプ。 |
uri |
string ping されるトラッキング イベント。 |
UniversalAdID
UniversalAdID は、広告システム間で維持される一意のクリエイティブ識別子を提供するために使用されます。JSON 表現 |
---|
{ "id_value": string, "id_registry": string, } |
フィールド | |
---|---|
id_value |
string 広告に選択したクリエイティブのユニバーサル広告 ID。 |
id_registry |
string 選択したクリエイティブのユニバーサル広告 ID がカタログ化されているレジストリ ウェブサイトの URL を識別するために使用される文字列。 |
コンパニオン モード
companion には、広告とともに表示されるコンパニオン広告に関する情報が含まれます。JSON 表現 |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], } |
フィールド | |
---|---|
click_data |
object(ClickData) このコンパニオンのクリックデータ。 |
creative_type |
string VAST の <StaticResource> ノードの CreativeType 属性(これが静的タイプのコンパニオンの場合)。 |
height |
int32 このコンパニオンの高さ(ピクセル単位)。 |
width |
int32 このコンパニオンの幅(ピクセル単位)。 |
resource |
string 静的コンパニオンと iframe コンパニオンの場合、これは読み込まれて表示される URL です。HTML コンパニオンの場合は、コンパニオンとして表示される HTML スニペットです。 |
type |
string このコンパニオンのタイプ。静的、iframe、HTML のいずれも使用できます。 |
ad_slot_id |
string このコンパニオンのスロット ID。 |
api_framework |
string このコンパニオンの API フレームワーク。 |
tracking_events |
[object(TrackingEvent)] このコンパニオンのトラッキング イベントのリスト。 |
InteractiveFile
InteractiveFile には、広告の再生中に表示する必要があるインタラクティブ クリエイティブの情報(SIMID など)が含まれます。JSON 表現 |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
フィールド | |
---|---|
resource |
string インタラクティブ クリエイティブの URL。 |
type |
string リソースとして提供されるファイルの MIME タイプ。 |
variable_duration |
boolean このクリエイティブで再生時間の延長をリクエストできるかどうか。 |
ad_parameters |
string VAST の <AdParameters> ノードの値。 |