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

Dynamic Ad Insertion API を使用すると、ダイナミック広告挿入のビデオ オンデマンド（VOD）ストリームをリクエストして追跡できます。HLS ストリームと DASH ストリームがサポートされています。

サービス: dai.google.com

stream メソッドのパスは https://dai.google.com からの相対パスです。

メソッド: stream

メソッド
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 されます。
DFP ターゲティング パラメータ 省略可 追加のターゲティング パラメータ。
ストリーム パラメータをオーバーライドする 省略可 ストリーム作成パラメータのデフォルト値をオーバーライドします。
HMAC 認証 省略可 HMAC ベースのトークンを使用して認証します。

レスポンスの本文

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

Open Measurement

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

方法: メディアの確認

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

media verification エンドポイントへのリクエストはべき等です。

メソッド
media verification GET {media_verification_url}/{ad_media_id}

メディアの検証イベントを API に通知します。

HTTP リクエスト

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

レスポンスの本文

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

  • HTTP/1.1 204 No Content: メディアの検証が成功し、すべてのピンが送信された場合。
  • HTTP/1.1 404 Not Found: URL の形式が正しくないか、期限切れのため、リクエストでメディアを検証できない場合。
  • HTTP/1.1 404 Not Found: この身分証明書に対する前回の確認リクエストが成功した場合。
  • HTTP/1.1 409 Conflict: 別のリクエストがすでに ping を送信している場合。

広告メディア ID（HLS）

広告メディア ID は、キー TXXX を使用して HLS タイムド メタデータでエンコードされます。このキーは「ユーザー定義テキスト情報」フレーム用に予約されています。フレームの内容は暗号化されず、常にテキスト "google_" で始まります。

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

広告メディア ID（DASH）

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

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

Response data

ストリーム

Stream は、新しく作成されたストリームのすべてのリソースのリストを 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

ストリーム ID。
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)]

ミッドロール挿入点のリスト。空の場合は省略。

AppleTV

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

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

AdBreak

AdBreak は、ストリーム内の 1 つのミッドロール挿入点を表します。位置、時間、タイプ（ミッドロール/プレロール/ポストロール）、広告のリストが含まれます。
JSON 表現
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
フィールド
type string

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

ミッドロール挿入点の開始位置（秒単位）。
duration number

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

広告のリスト。空の場合は省略。
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),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
フィールド
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)]

ラッパーのリスト。空の場合は省略。
events [object(Event)]

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

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

オプションのユニバーサル広告 ID。
companions [object(Companion)]

この広告とともに表示されるコンパニオン（省略可）。
interactive_file object(InteractiveFile)

広告の再生中に表示するオプションのインタラクティブ クリエイティブ（SIMID）。
skip_metadata object(SkipMetadata)

スキップ可能な広告のオプションのメタデータ。設定されている場合、広告はスキップ可能であり、スキップ UI とトラッキング イベントを処理する方法が記載されています。
extensions string

VAST 内のすべての <Extension> ノードのリスト（省略可）。

イベント

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（省略可）。

SkipMetadata

SkipMetadata は、スキップ可能な広告のスキップ イベントをクライアントが処理するために必要な情報を提供します。
JSON 表現
{
  "offset": number,
  "tracking_url": string,
}
フィールド
offset number

オフセットは、スキップボタンをレンダリングするまでプレーヤーが待機する広告内の時間（秒単位）を示します。VAST で指定されていない場合は省略されます。
tracking_url string

TrackingURL には、スキップ イベントで ping を送信する 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

ラッパー

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 を識別するために使用される文字列。

コンパニオン モード

コンパニオンには、広告とともに表示されるコンパニオン広告に関する情報が含まれます。
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> ノードの値。