ダイナミック広告挿入の VOD API

Dynamic Ad Insertion API を使用すると、DAI ビデオ オンデマンド（VOD）ストリームをリクエストしてトラッキングできます。HLS と DASH のストリームがサポートされています。

サービス: dai.google.com

stream メソッドのパスは https://dai.google.com を基準とする

メソッド: stream

Methods
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

指定されたコンテンツ ソースと動画 ID の HLS DAI ストリームを作成します。

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

指定されたコンテンツ ソースと動画 ID の DASH DAI ストリームを作成します。

HTTP リクエスト

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

リクエスト ヘッダー

パラメータ
api‑key string

ストリームの作成時に指定する API キーは、パブリッシャーのネットワークに対して有効である必要があります。

API キーは、リクエストの本文で指定する代わりに、HTTP Authorization ヘッダーで次の形式で渡すことができます。

Authorization: DCLKDAI key="<api-key>"

パスパラメータ

パラメータ
content-source string

ストリームの CMS ID。

video-id string

ストリームの動画 ID。

リクエスト本文

リクエストの本文は application/x-www-form-urlencoded 型で、次のパラメータを含みます。

パラメータ
dai-ssb 任意

サーバーサイド ビーコン ストリームを作成するには、true に設定します。デフォルトは false です。デフォルト ストリームのトラッキングはクライアントによって開始され、サーバー側で ping されます。
Chronicle のターゲティング パラメータ 任意 追加のターゲティング パラメータ。
ストリーム パラメータをオーバーライドする 任意 ストリーム作成パラメータのデフォルト値をオーバーライドします。
HMAC 認証 任意 HMAC ベースのトークンを使用して認証します。

レスポンスの本文

成功した場合、レスポンスの本文には新しい Stream が含まれます。サーバーサイド ビーコン ストリームの場合、この Stream には stream_id フィールドと stream_manifest フィールドのみが含まれます。

Open Measurement

Verifications フィールドには、非サーバーサイド ビーコン ストリームの Open Measurement 検証に関する情報が含まれます。Verifications には 1 つ以上の Verification 要素が含まれます。これらの要素は、第三者測定コードでクリエイティブの再生を検証するために必要なリソースとメタデータをリストします。JavaScriptResource のみがサポートされています。詳しくは、IAB Tech Lab と VAST 4.1 仕様をご覧ください。

方法: メディアの確認

再生中に広告メディア ID を見つけたら、すぐに stream エンドポイントから media_verification_url を使用してリクエストを行います。media_verification_url は絶対パスです。サーバーがメディア検証を開始するサーバーサイド ビーコン ストリームでは、メディア検証リクエストは必要ありません。

media verification エンドポイントへのリクエストはべき等になります。

Methods
media verification GET {media_verification_url}/{ad_media_id}

API にメディア確認イベントを通知します。

HTTP リクエスト

GET {media-verification-url}/{ad-media-id}

レスポンスの本文

media verification は次のレスポンスを返します。

  • メディアの確認に成功し、すべての ping が送信された場合は HTTP/1.1 204 No Content。
  • HTTP/1.1 404 Not Found。URL の形式が正しくないため、または有効期限が原因でメディアを検証できない場合。
  • HTTP/1.1 404 Not Found: この ID の以前の確認リクエストが成功した場合。
  • HTTP/1.1 409 Conflict: この時点で別のリクエストがすでに ping を送信している場合。

広告メディア ID（HLS）

広告メディア識別子は、「ユーザー定義のテキスト情報」フレーム用に予約されたキー TXXX を使用して、HLS 時間指定メタデータでエンコードされます。フレームのコンテンツは暗号化されず、常に "google_" というテキストで始まります。

広告確認リクエストごとに、フレームのテキスト コンテンツ全体を media_verification_url に追加する必要があります。

広告メディア ID（DASH）

広告メディア ID は、DASH の EventStream 要素を使用してマニフェストに挿入されます。

各 EventStream には、urn:google:dai:2018 のスキーム ID URI が含まれます。このイベントには、“google_” で始まる広告メディア ID を含む messageData 属性を持つイベントが含まれます。広告確認リクエストごとに、messageData 属性の内容全体を media_verification_url に追加する必要があります。

Response data

ストリーム

ストリームは、新しく作成されたストリームのすべてのリソースのリストを JSON 形式でレンダリングするために使用されます。
JSON 表現
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
フィールド
stream_id string

ストリーム識別子。
total_duration number

ストリーミング時間（秒）。
content_duration number

広告なしのコンテンツの再生時間（秒単位）。
valid_for string

再生時間のストリームの有効期間は「00h00m00s」形式。
valid_until string

ストリームの有効期限（RFC 3339 形式）。
subtitles [object(Subtitle)]

字幕のリスト。空の場合は省略されます。HLS のみ。
hls_master_playlist string

（非推奨）HLS マスター再生リストの URL。stream_manifest を使用します。HLS のみ。
stream_manifest string

ストリームのマニフェスト。HLS のマスター再生リストと DASH の MPD に対応します。サーバーサイド ビーコン ストリームの作成時にレスポンスに存在する、「stream_id」以外の唯一のフィールドです。
media_verification_url string

メディア確認 URL。
apple_tv object(AppleTV)

AppleTV デバイスに固有のオプション情報。HLS のみ。
ad_breaks [object(AdBreak)]

AdBreak のリスト。空の場合は省略されます。

AppleTV

AppleTV には、Apple TV デバイスに固有の情報が含まれています。
JSON 表現
{
  "interstitials_url": string,
}
フィールド
interstitials_url string

インタースティシャルの URL。

AdBreak

AdBreak は、ストリーム内の 1 つの広告ブレークを示します。位置、再生時間、タイプ（mid/pre/post）、広告のリストが含まれます。
JSON 表現
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
フィールド
type string

有効な挿入タイプは、mid、pre、post です。
start number

ストリーム内での休憩の開始位置（秒単位）。
duration number

広告ブレークの長さ（秒単位）。
ads [object(Ad)]

広告のリスト。空の場合は省略されます。
広告はストリーム内の広告を表します。広告ブレーク内の広告の位置、広告の再生時間、オプションのメタデータが含まれます。
JSON 表現
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
フィールド
seq number

広告ブレーク内の広告の位置。
start number

ストリーム内での広告表示が始まる位置（秒単位）。
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（省略可）。
icons [object(Icon)]

アイコンのリスト。空の場合は省略されます。
wrappers [object(Wrapper)]

Wrapper のリスト。空の場合は省略されます。
events [object(Event)]

広告内のイベントのリスト。
verifications [object(Verification)]

Open Measurement 検証エントリ（省略可）。第三者の測定コードを実行してクリエイティブの再生を検証するために必要なリソースとメタデータをリストします。
universal_ad_id object(UniversalAdID)

ユニバーサル広告 ID（省略可）。
companions [object(Companion)]

この広告とともに表示できるオプションのコンパニオン。
interactive_file object(InteractiveFile)

広告の再生中に表示されるオプションのインタラクティブ クリエイティブ（SIMID）。

イベント

Event には、イベントの種類と、イベントの提示時間が格納されます。
JSON 表現
{
  "time": number,
  "type": string,
}
フィールド
time number

この予定のプレゼンテーション時間。
type string

このイベントのタイプ。

字幕

サブタイトルは、動画ストリームのサイドカー サブタイトル トラックを表します。TTML と WebVTT の 2 つの字幕形式が格納されます。TTMLPath 属性には TTML サイドカー ファイルの URL が含まれ、WebVTTPath 属性にも同様に WebVTT サイドカー ファイルの URL が含まれます。
JSON 表現
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
フィールド
language string

「en」や「de」などの言語コード。
language_name string

言語のわかりやすい名前。同じ言語に複数のセットが存在する場合、特定の字幕セットを区別します。
ttml string

TTML サイドカー ファイルの URL（省略可）。
webvtt string

WebVTT サイドカー ファイルの URL（省略可）。

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

ラッパー

ラッパーには、ラッパー広告に関する情報が含まれます。取引 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（省略可）。

検証

Verification には 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

トラッキング イベントのタイプ。現時点では、VAST 4.1 仕様で指定されている「verificationNotExecuted」のみがオプションです。
uri string

ping を送信するトラッキング イベント。

UniversalAdID

UniversalAdID は、広告システム全体で維持される固有のクリエイティブ ID を提供するために使用されます。
JSON 表現
{
  "id_value": string,
  "id_registry": string,
}
フィールド
id_value string

広告に対して選択されたクリエイティブのユニバーサル広告 ID。
id_registry string

選択したクリエイティブのユニバーサル広告 ID がカタログに登録されているレジストリのウェブサイトの URL を識別するために使用される文字列。

コンパニオン

コンパニオンには、広告とともに表示できるコンパニオン広告の情報が含まれます。
JSON 表現
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
}
フィールド
click_data object(ClickData)

このコンパニオンのクリックデータ。
creative_type string

VAST の <StaticResource> ノードの CreativeType 属性（静的タイプのコンパニオンの場合）。
height int32

このコンパニオンの高さ（ピクセル単位）。
width int32

このコンパニオンの幅（ピクセル単位）。
resource string

静的コンパニオンと iframe コンパニオンの場合は、読み込まれて表示される URL になります。HTML コンパニオンの場合は、コンパニオンとして表示される HTML スニペットになります。
type string

このコンパニオンのタイプ。静的、iframe、HTML のいずれかを使用できます。

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> ノードの値。