ビデオクラウドSSAI API

このトピックでは、サーバー側の広告挿入（SSAI）APIを使用して広告構成を作成および管理する方法を学習します。

広告設定は、広告コール、ビーコン、その他の設定オプションを含む、SSAI 再生のさまざまな側面を定義します。アカウントは複数の構成を持つことができ、現在の設定はアカウント間で共有できません。

一般情報

以下の情報は、すべての SSAI API リクエストに関連します。

ベース URL

SSAI API のベース URL は次のとおりです。

https://ssai.api.brightcove.com/v1

アカウントパス

いずれの場合も、特定の Video Cloud アカウントに対してリクエストが行われます。したがって、accountsあなたは常にベースURLにアカウントIDが続く用語を追加します：

https://ssai.api.brightcove.com/v1/accounts/your account id

認証

要求の認証には、Authorization ヘッダーが必要です。

Authorization: Bearer your access token

access_tokenは一時的な OAuth2 アクセストークンで、Brightcove OAuth サービスから取得する必要があります。クライアントの資格情報を取得し、それらを使用してアクセストークンを取得する方法の詳細については、 BrightcoveAPIリクエストの認証。

オペレーション

クライアントの資格情報を要求するときは、必要なアカウントアクセスの種類または操作を指定する必要があります。以下は、SSAI API に対して現在サポートされている操作の一覧です。

SSAI データ:
video-cloud/ssai/read
video-cloud/ssai/all

広告設定の管理

API は、次の GET および PUT リクエストをサポートします。

広告構成の一覧表示
広告設定を作成する
広告設定の詳細を取得する
広告設定の更新

広告構成の一覧表示

アカウントに対して定義された広告設定を一覧表示します。

方法	取得する
URL	https://ssai.api.brightcove.com/v1/accounts/ あなたのアカウント ID /ssai_configs
ヘッダー	認証：アクセストークンをベアラする
ヘッダー	コンテンツタイプ:アプリケーション/JSON

レスポンスの例:

[
  {
    "name": "VMAP Ad Server",
    "vmap_response_namespace": "bc",
    "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
    "account_id": "57838016001",
    "created_timestamp": "2017-07-24T19:28:34.976878586Z",
    "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
      }
    }
  }
]

広告設定を作成する

アカウントの広告設定を作成します。

方法	役職
URL	https://ssai.api.brightcove.com/v1/accounts/ あなたのアカウント ID /ssai_configs
ヘッダー	認証：アクセストークンをベアラする
ヘッダー	コンテンツタイプ:アプリケーション/JSON

サンプル本文:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_config": {
  	"expected_ad_response": "vast_3_0",
  	"disable_server_beacons": false,
    "round_up_cue_points": false,
  	"template_url": {
  		"template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
  	}
  },
  "discontinuities": {
    "hls": [ "*" ]
  }
}

広告設定の詳細を取得する

アカウントの場合、設定 ID で広告設定の詳細を取得します。

方法	取得する
URL	https://ssai.api.brightcove.com/v1/accounts/ あなたのアカウント ID /ssai_configs/ 広告設定ID
ヘッダー	認証：アクセストークンをベアラする
ヘッダー	コンテンツタイプ:アプリケーション/JSON

レスポンスの例:

	{
		"name": "VMAP Ad Server",
		"vmap_response_namespace": "bc",
		"config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
		"account_id": "57838016001",
		"created_timestamp": "2017-07-24T19:28:34.976878586Z",
		"updated_timestamp": "2017-07-24T19:28:34.976878586Z",
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
					"template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
			}
		},
		"beacon_templates": [
				{
					"type": "content_start",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "content_midpoint",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "ad_start",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				},
				{
					"type": "content_complete",
					"template_url": {
						"template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
					}
				}
			],
			"discontinuities": {
				"dash": [
					"*"
				],
				"hls": [
					"*"
				]
			},
			"extend_beacon_guard_ttl": true
		}
	}

広告設定の更新

設定 ID で広告設定を更新します。

方法	置きます
URL	https://ssai.api.brightcove.com/v1/accounts/ あなたのアカウント ID /ssai_configs/ 広告設定ID
ヘッダー	認証：アクセストークンをベアラする
ヘッダー	コンテンツタイプ:アプリケーション/JSON
サンプルボディ	`{ "name": "VMAP Ad Server - updated" }`

レスポンスの例:

	{
		"name": "VMAP Ad Server - updated",
		"vmap_response_namespace": "bc",
		"config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
		"account_id": "57838016001",
		"created_timestamp": "2017-07-24T19:28:34.976878586Z",
		"updated_timestamp": "2017-07-24T19:28:34.976878586Z",
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
				"template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
			}
		}
	}

設定フィールドの詳細

この表は、リクエストの本文セクション内で使用される広告設定フィールドを定義します。

フィールド	タイプ	説明
`name`	文字列	人間が読める名前
`vmap_response_namespace`	文字列	従来の Unicorn Once 名前空間形式を使用するか、新しい Brightcove 名前空間形式を使用するように VMAP 出力を調整します。値：`uo`、`bc`ディフォルト：`bc`
`description`	文字列	人間が読める説明
`ad_config.expected_ad_response`	文字列	応答を解析するために使用する技術。 ^[1] 値: `dfp_ad_rules` `dfp_vmap` `smart_xml` `vast_3_0`
`ad_config.disable_server_beacons`	ブール値	広告インプレッション/ビーコンのサーバー側の起動を無効にするかどうかにフラグを立てますに設定した場合`true`、SSAIはサーバー側でビーコンを起動せず、VMAP出力にすべてのビーコンを含めますに設定した場合`false`、SSAIは、サーバー側で実行できるビーコンを起動し、VMAP出力に送信できないビーコンを含めます。
`ad_config.round_up_cue_points`	ブール値	広告を挿入する近くの位置を選択するときに、次のキーフレームに切り上げるかどうかを設定します。ディフォルト：`false`、目的の広告位置に最も近いキーフレームを選択します。
`ad_config.template_url.template`	文字列	広告タグテンプレート。使用可能な変数については、後のセクションで説明しています。
`ad_config.template_url.defaults`	オブジェクト	URLパラメータが指定されていない場合に使用するデフォルトを定義する文字列への文字列へのマップ。文字通りにすることができます`{ "url.foo": "SomeString" }` または別の変数を参照する`{ "url.foo": "{{ metadata.title_id }}" }`
`discontinuities.dash` ^[2]	[] 文字列	複数ピリオド Dash マニフェストを提供するダッシュのバージョンを制御します。に設定`["*"]`すべてのバージョンに複数期間のダッシュを配信する決して空のリスト例：`["live-timeline"]`ライブタイムラインには配信しますが、hbbtvには配信しません
`discontinuities.hls` ^[2]	[] 文字列	不連続性で配信する hl のバージョンを制御します。に設定`["*"]` HLSのすべてのバージョンで不連続性のある配信決して空のリスト例：`["v4","v5"]` v4とv5には配信されますが、v3には配信されません
`beacon_templates`	配列	起動するビーコンの配列（例:サードパーティビーコン）
`beacon_templates[].type`	文字列	発射するビーコンのタイプ。値: `content_start` `content_first_quartile` `content_midpoint` `content_third_quartile` `content_complete` `content_quartiles` `content_interval` `ad_start` `ad_first_quartile` `ad_midpoint` `ad_third_quartile` `ad_complete` `ad_quartiles` `ad_break_start` `ad_break_end` `segment_start` `segment_end` `on_load`
`beacon_templates[].template_url.template`	文字列	ビーコン URL テンプレート
`extend_beacon_guard_ttl`	ブール値	ビーコンガード TTL（存続時間）の長さを、コンテンツのセッション TTL の長さに設定します。それ以外の場合、デフォルトは 1 分です。

次の注意事項は、上の表のフィールドを参照してください。

^[1] いつexpected_ad_responseに設定されていますvast_3_0、SSAIは、VideoCloudで定義されたアドキューポイントごとに1つのVAST呼び出しを行います。VMAP および広告ルールの場合、SSAI は最初の広告応答で定義された広告ブレークに基づいてリクエストを行います。

^[2] 不連続タグは、コンテンツビデオと広告セグメント間のフレームレートエンコーディングの変更を示します。レンダリングチェーンを再構築するようにシステムに指示します。スケーラブルなSSAIの場合、ビデオプレーヤーは、不連続タグと複数のピリオドを含む MPEG DASH で HLS を再生できる必要があります。

広告変数

テンプレートURL内の変数は、変数パスの前と後にオプションの空白を含む二重中括弧（{{ … }}）で識別されます。すべての変数には、次の 3 つの名前空間のうちの 1 つが付きます。

システム
url
メタデータ

システム変数

システム変数は SSAI システムによって提供され、エンドユーザーまたはランダム値を生成するためのヘルパー変数に関する情報です。値は、URL テンプレートに挿入する前に URI エンコードされている必要があります。

システム変数は次のように識別されます。{{system.*}}

フィールド	説明
`ad.position_time`	広告リクエストをトリガーしたキューポイントの秒単位の時間。 VAST広告応答タイプでのみ使用可能
`ip_address`	エンドユーザーのIPアドレス
`random_number_32`	ランダム32ビット整数
`random_guid`	ランダム UUID
`referer`	エンドユーザーのリファラーヘッダー値
`timestamp_utc`	Unixタイムスタンプとしての現在の時刻
`unique_user_id`	MD5 (IPアドレス+ユーザー_エージェント)
`unix_timestamp`	UNIXタイムスタンプ（秒）としての現在の時刻
`user_agent`	エンドユーザーのユーザーエージェントヘッダー値
`uuid`	ランダムUUID
`x_forwarded_for`	エンドユーザーのXフォワード For ヘッダー値
`xfp.correlator`	ランダム64ビット整数
`xfp.ip_address`	エンドユーザーのIPアドレス
`xfp.unique_user_id`	MD5 (IPアドレス+ユーザー_エージェント)
`xfp.scor`	ランダム64ビット整数

URL 変数

エントリポイント VMAP/マニフェストで提供されるクエリパラメーターは、url名前空間の下で使用できます。他の名前空間の変数とは異なり、これらのパラメータはテンプレートに挿入するときにURLエンコードされません。変数値は、広告プロバイダに行くURLエンコードする必要がある場合は、エントリポイントURLで二重URLエンコードする必要があります。

URL 変数は次のように識別されます。{{url.*}}

メタデータ変数

メタデータ変数は、Video Cloud データソースと動的配信データソースの両方から派生したコンテンツビデオを表す変数です。値は、URL テンプレートに挿入される前に URL エンコードされます。

メタデータ変数は次のように識別されます。{{metadata.*}}

フィールド	説明
`ad_keys`	Video Cloud Studio Media モジュールで追加および編集できる自由形式のテキスト文字列
`custom_fields.{field_name}`	ビデオクラウドのカスタムフィールド
`long_description`	ビデオクラウドの詳細説明
`name`	ビデオクラウドの動画名
`reference_id`	ビデオクラウド参照 ID
`tags`	動画の Video Cloud タグのコンマ区切りのリスト
`title.duration`	コンテンツの継続時間 (秒)
`title.id`	動的配信タイトルID
`title.name`	動的配信のタイトル名
`video_id`	ビデオクラウド動画 ID
その他の Video Cloud キー/値のペアもここにあります

エントリポイント URL パラメータ

いくつかの動作を調整するために、SSAI エントリポイント URL（VMAP またはマニフェスト）に追加できるクエリパラメーターがいくつかあります。

パラメーター	説明
`?rule=sd-only`	アカウント設定で設定されたしきい値よりも低い高さのビデオレンディションをすべて除外します。
`?rule=discos-enabled`	Dash で HLS & マルチピリオドで不連続で再生を有効にします。[再生設定] の [不連続性] 設定よりも優先されます
`?rule=discos-disabled`	DashのHLSとマルチピリオドで不連続での再生を無効にします。[再生設定] の [不連続性] 設定よりも優先されます

構成に関する注意事項

広告のプリロードはSSAIで行うべきではありません。この理由は、プレロードすると、プレーヤーが広告インプレッションを報告し、おそらく動画が再生される前の最初の四分位ビーコンを報告するからです。これにより、広告分析が不正確になる可能性があります。StudioでSSAIを構成すると、これは自動的に行われますが、SSAIを手動でセットアップする場合は、この問題に注意する必要があります。
ウェブプレーヤーが SSAI を使用していて、その動機の 1 つが広告ブロッカーを回避することである場合は、サーバー側のビーコンを使用する必要があります。クライアント側のビーコンはブロックされるため使用しないでください。

クライアント側マクロ

クライアント側の広告マクロを使用する場合は、pageプレフィックスを使用します。これらのマクロを使用すると、VMAP およびサーバーの URL で変数を使用できます。広告マクロの詳細については、「IMA3 プラグインによる広告」ドキュメントの「広告マクロ」および「ServerURL 」セクションを参照してください。

クライアント側マクロには、次の接頭辞が付けられます。{{page.*}}

たとえば、document.referrerとpageVariable DOM ウィンドウ変数を追加するには、page広告テンプレートで次のように接頭辞を付けます。

https://adserver.com/{{page.document.referrer}}/{{page.pageVariable.whateverIwant}}

Playback API document.referrerが返され、VMAP および SRC URL pageVariable.whateverIwantに追加されます。次に、Brightcove Player は、リクエストを送信する前に、クライアント側マクロ置換ロジックを実行し、適切な値を置き換えます。

https://bolt-prefix/blah.vmap?document.referrer={document.referrer}&pageVariable.whateverIwant={pageVariable.whateverIwant}

広告エラービーコン

SSAI を使用する際の VAST 広告エラービーコンは、広告ワークフローに関する問題をプロアクティブに検出して解決するのに役立ちます。詳細については、「 SSAI を使用した広告エラービーコン」のドキュメントを参照してください。

ページコンテンツ

ビデオクラウドSSAI API

一般情報

ベース URL

アカウントパス

認証

オペレーション

広告設定の管理

広告構成の一覧表示

広告設定を作成する

広告設定の詳細を取得する

広告設定の更新

設定フィールドの詳細

広告変数

システム変数

URL 変数

メタデータ変数

エントリポイント URL パラメータ

構成に関する注意事項

クライアント側マクロ

広告エラービーコン