視頻雲 SSAI API

廣告組態可定義 SSAI 播放的各個層面，包括廣告通話、信標和其他組態選項。一個帳戶可以有多個配置，目前的配置無法在帳戶之間共享。

一般資訊

下列資訊適用於所有 SSAI API 要求。

基本網址

SSAI API 的基本網址為：

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

帳號路徑

在所有情況下，我們都會針對特定的視訊雲端帳戶提出要求。因此，您始終將該術語accounts後跟您的帳戶 ID 添加到基本 URL 中：

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

驗證

請求的身份驗證需要一個授權標頭：

Authorization: Bearer your access token

這access_token是一個臨時的 OAuth2 訪問令牌，必須從布萊特灣 OAuth 服務獲得。有關如何獲取客戶端憑據並使用它們檢索訪問令牌的詳細信息，請參閱 Brightcove API 請求的身份驗證。

作業

當您要求用戶端認證時，您必須指定您想要的帳戶存取或作業類型。以下是 SSAI API 目前支援的作業清單：

SSAI 資料：
video-cloud/ssai/read
video-cloud/ssai/all

管理廣告配置

該API支持以下GET和PUT請求：

列出廣告配置
建立廣告組態
獲取廣告配置詳細信息
更新廣告配置

列出廣告配置

列出為帳戶定義的廣告配置。

方法	得到
URL	https://ssai.api.brightcove.com/v1/accounts/ 您的帳戶編號/設定
標頭	授權：承載您的訪問令牌
標頭	內容類型：應用程序/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": "https://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/ 您的帳戶編號/設定
標頭	授權：承載您的訪問令牌
標頭	內容類型：應用程序/JSON

樣品體：

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_tracking_sample_percentage": 100,
  "ad_config": {
    "expected_ad_response": "vast_3_0",
    "disable_server_beacons": false,
    "round_up_cue_points": false,
    "template_url": {
      "template": "https://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": [ "*" ]
  }
}

有關字段定義，請參閱配置字段詳細信息部分。

注意事項

ad_tracking_sample_percentage確定將記錄的會話百分比。它可以是 0（禁用日誌記錄）到 100（記錄所有會話）之間的任何值。

獲取廣告配置詳細信息

對於帳戶，請按config ID獲取廣告配置詳細信息。

方法	得到
URL	https://ssai.api.brightcove.com/v1/accounts/ 您的帳戶 ID /ssai_配置/ 您的廣告配置識別碼
標頭	授權：承載您的訪問令牌
標頭	內容類型：應用程序/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_tracking_sample_percentage": 100,
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
					"template": "https://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_配置/ 您的廣告配置識別碼
標頭	授權：承載您的訪問令牌
標頭	內容類型：應用程序/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": "https://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`	字串	調整VMAP輸出以使用舊的Unicorn Once名稱空間格式或使用新的Brightcove名稱空間格式。值：`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`	物件	String到String的映射，定義了在未提供url參數的情況下使用的默認值。可以是文字`{ "url.foo": "SomeString" }` 或引用另一個變量`{ "url.foo": "{{ metadata.title_id }}" }`
`ad_tracking_sample_percentage`	整數	此值確定將記錄的會話百分比。它可以是任何值`0`（禁用日誌記錄）到`100`（記錄所有會話）。的價值`0`完全禁用日誌。默認：`0` 價值觀：`[ 0 .. 100 ]`
`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`	字串	信標網址模板
`discontinuities.dash`^[2]	[] 字串	控制傳遞多個時期破折號清單的破折號的版本。設置為`["*"]`為所有版本提供多週期破折號從不為空列表示例：`["live-timeline"]`為實時時間線提供，但不為 hbbtv 提供
`discontinuities.hls`^[2]	[] 字串	控制不連續交付的hls版本。設置`["*"]`為在所有版本的 HLS 中不連續的交付永不為空列表示例：`["v4","v5"]`為 v4 和 v5 提供，但不為 v3 提供
`extend_beacon_guard_ttl`	布林值	將信標保護TTL的長度（生存時間）設置為內容會話TTL的長度。否則，默認值為1分鐘。

廣告響應類型

這是有關使用的一些其他信息ad_config.expected_ad_response上表中的類型。值：

vast_3_0 - 數字視頻廣告服務模板 (VAST)
dfp_vmap - 視頻多廣告播放列表 (VMAP)
dfp_ad_rules - Google DFP 的專有格式，已更名為 Google Ad Manager(GAM)
smart_xml - FreeWheel 的專有格式

處理流程

創建 SSAI 廣告配置時，請牢記以下流程說明：

虛擬映射

如果 SSAI Config 的廣告響應類型是 DFP VMAP：

任何配置有視頻的提示點都將被忽略。
SSAI 解析來自廣告提供商的 VMAP XML 文件，其中包含所有廣告及其定義的位置。

VAST

如果 SSAI Config 的廣告響應類型是 VAST 3.0：

在您的視頻中定義提示點。SSAI 會對視頻中的每個提示點發出請求，以構建廣告插播點。
如果視頻沒有配置提示點，則默認插入前置廣告。

廣告變數

模板 url 中的變量由雙花括號（{{ … }}）與變量路徑之前和之後的可選空白標識。所有變量都以三個名稱空間之一作為前綴：

系統
網址
元數據

系統變量

系統變量由SSAI系統提供，並且可以是有關最終用戶或輔助變量的信息，以生成隨機值。在將值插入URL模板之前，必須先對其進行URI編碼。

系統變數被識別為：{{system.*}}

欄位	描述
`ad.position_time`	觸發廣告請求的提示點的時間（以秒為單位）；僅適用於 VAST 廣告響應類型
`ip_address`	一般使用者的 IP 位址
`random_number_32`	隨機32位整數
`random_number_<min>_<max>`	在兩個數字之間生成一個隨機數。接受的範圍從 0 到最大值`UInt32` .只允許正數，並且`min`必須低於`max`
`random_guid`	隨機UUID
`referer`	最終用戶的引薦來源標頭值
`timestamp_utc`	當前時間作為Unix時間戳
`unique_user_id`	MD5 (IP 位址 + 使用者代理程式)
`unix_timestamp`	當前時間（Unix時間戳）（秒）
`user_agent`	最終用戶的User-Agent標頭值
`uuid`	隨機uuid
`x_forwarded_for`	最終用戶的X-Forwarded-For標頭值
`xfp.correlator`	隨機 64 位元整數
`xfp.ip_address`	一般使用者的 IP 位址
`xfp.unique_user_id`	MD5 (IP 位址 + 使用者代理程式)
`xfp.scor`	隨機 64 位元整數

URL變量

在進入點 VMap/ 資訊清單上提供的查詢參數可在url命名空間下使用。與其他命名空間下的變量不同，這些參數在插入模板時不會進行url編碼。如果需要對變量值進行網址編碼，然後轉到廣告提供商，則必須在入口點網址上對它們進行雙網址編碼。

URL 變量被標識為：{{url.*}}

需要使用自定義集成替換 URL 變量，如下所示：

編寫代碼以向 Playback API 發出請求。
攔截 API 請求返回的數據。
替換任何{{url.*}}源 URL 中的標記
將數據/源加載到播放器（Brightcove Player for web 或 Native SDK）

元數據變量

元數據變量是描述內容視頻的變量，這些變量既來自視頻雲又來自動態交付數據源。價值（除了ad_keys )在插入到 URL 模板之前進行 URL 編碼。

ad_keys旨在填充單獨的查詢參數以傳遞給廣告服務器，因此 url 編碼會破壞它。

中繼資料變數會識別為：{{metadata.*}}

欄位	描述
`ad_keys`	可以使用以下兩個字段之一在 Video Cloud Studio 媒體模塊中添加和編輯的自由格式文本字符串，具體取決於您的廣告響應類型 Non Vast 3.0 - “Ad Keys”視頻字段 Vast 3.0 - “廣告鍵”視頻字段與視頻提示點上的“鍵/值對”字段連接在一起。要了解如何使用提示點，請參閱媒體模塊文檔中的使用提示點。
`custom_fields.{field_name}`	Video Cloud自定義字段
`long_description`	視頻雲詳細說明
`name`	視頻雲視頻名稱
`reference_id`	視頻雲參考ID
`tags`	視頻的視頻雲標籤的逗號分隔列表
`title.duration`	內容持續時間（以秒為單位）
`title.id`	動態投放標題ID
`title.name`	動態投放標題名稱
`video_id`	視頻雲視頻ID
其他視頻雲鍵/值對也將在此處

入口點URL參數

可以將少量查詢參數添加到SSAI入口點URL（VMAP或清單）以調整某些行為：

參數	描述
`?rule=sd-only`	過濾掉任何高度小於“帳戶配置”中設置的閾值的視頻演示
`?rule=discos-enabled`	在Dash中的HLS和MultiPeriods中啟用不連續播放。優先於播放配置中的不連續性設置
`?rule=discos-disabled`	在Dash中的HLS和MultiPeriods中禁用不連續播放。優先於播放配置中的不連續性設置

組態注意事項

預先載入廣告不應使用 SSAI 進行。原因是，如果您預先載入，播放器將會回報廣告印象，也可能是影片播放前的第一個四分位元信標。這可能會導致不準確的廣告分析。如果您在 Studio 中配置 SSAI，這將自動完成，但如果您碰巧手動設置 SSAI，則需要注意此問題。
如果網路播放程式使用 SSAI，而您這樣做的動機之一就是解決廣告封鎖程式，您應該使用伺服器端信標。不應該使用用戶端信標，因為它們將被封鎖。

客戶端宏

如果您想要使用用戶端廣告巨集，請使用page前置詞。這些宏使您可以在VMAP和服務器URL中使用變量。如需廣告巨集詳細資訊，請參閱使用 IM3 外掛程式文件廣告的廣告巨集和 ServerUrl 一節。

客戶端宏的前綴為：{{page.*}}

舉例來說，若要新增document.referrer和pageVariable DOM 視窗變數，您可以在廣告範本page中加上前置詞，如下所示：

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

播放 API 會傳回document.referrer並pageVariable.whateverIwant附加至 VMAP 和 SRC 網址。然後，在發送請求之前，Brightcove播放器將通過其客戶端宏替換邏輯來替換適當的值：

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

廣告錯誤信標

使用SSAI時，VAST廣告錯誤信標有助於主動發現和解決廣告工作流程中的問題。如需詳細資訊，請參閱 SSAI 的廣告錯誤信標文件。