ダイナミック広告挿入の連続配信広告のライブ API

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 は、広告ブレーク イベントごとに、1 から段階的に割り当てられます。

ad_break_id/{string}

現在のミッドロール挿入点の文字列 ID。
profile_name string

リクエストされた Google アド マネージャー DAI エンコード プロファイルの名前。エンコード プロファイルは、選択したイベント用に構成されたエンコード プロファイルのいずれかである必要があります。
segment_number integer

現在の広告連続配信内のリクエストされたセグメントのインデックス（0 から始まる）。
segment_format string

リクエストされたセグメント形式に関連付けられたファイル拡張子。使用できる拡張機能は ts、mp4、vtt、aac、ac3、eac3 です。

クエリ パラメータ

パラメータ
stream_id 必須 string

現在のユーザーのセッションのストリーム ID。この値は、stream エンドポイントへのリクエストが成功すると返されます。
sd required1 integer

リクエストされたセグメントの長さ（ミリ秒単位）。
so 省略可

連続配信広告内のリクエストされたセグメントのオフセット（ミリ秒単位）。so パラメータを省略すると、セグメントの長さ × セグメント番号で計算されます。
pd 必須2 integer

連続配信広告の再生時間（ミリ秒単位）。
auth-token 必須 string

現在の広告連続配信の署名付き URL エンコード HMAC トークン。
last 省略可 boolean

広告ブレーク内の最後のセグメントを示します。他のすべてのセグメントでは、このパラメータを省略します。
scte35 省略可 string

この広告ブレークの Base64 でエンコードされた SCTE-35 シグナル。
cust_params 省略可 string

アド マネージャー キャンペーンのターゲティングに使用される Key-Value ペアのセット。これらのペアは、URL エンコードされたクエリ文字列として表す必要があります。

例:
パラメータ
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

脚注

  1. 初期化セグメントには sd は必要ありません。↩
  2. 長さのないミッドロール挿入点が有効になっているイベントでは、pd は必要ありません。↩

例

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 は、広告ブレーク イベントごとに 1 から順番に割り当てられます。

クエリ パラメータ

パラメータ
stream_id 必須 string

現在のユーザーのセッションのストリーム ID。この値は、stream エンドポイントへのリクエストが成功すると返されます。
pd 必須 integer

連続配信広告の再生時間（ミリ秒単位）。
scte35 省略可 string

この広告ブレークの Base64 でエンコードされた SCTE-35 シグナル。
cust_params 省略可 string

アド マネージャー キャンペーンのターゲティングに使用される Key-Value ペアのセット。これらのペアは、URL エンコードされたクエリ文字列として表す必要があります。

例:
パラメータ
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

レスポンスの本文

成功すると、レスポンスの本文は 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。この値は、stream エンドポイントへのリクエストが成功すると返されます。
pod_id integer

現在のミッドロール挿入点の数値識別子。連続配信広告 ID は、広告ブレーク イベントごとに、1 から段階的に割り当てられます。

クエリ パラメータ

パラメータ
pd 必須 integer

連続配信広告の再生時間（ミリ秒単位）。
scte35 省略可 string

この広告ブレークの Base64 でエンコードされた SCTE-35 シグナル。
cust_params 省略可 string

アド マネージャー キャンペーンのターゲティングに使用される Key-Value ペアのセット。これらのペアは、URL エンコードされたクエリ文字列として表す必要があります。

例:
パラメータ
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

レスポンスの本文

成功した場合、レスポンスの本文は 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。この値は、stream エンドポイントへのリクエストが成功すると返されます。

レスポンスの本文

成功した場合、レスポンスの本文には新しい 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> ノードの値。