此頁面已移動 - 您將在 3 秒內轉到 新位置 。請更新您的書籤！

視頻雲服務廣告配置 API

在本主題中，您將學習如何使用伺服器端廣告插入 (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 OAuth 概述。

作業

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

  • SSAI 資料：

    video-cloud/ssai/read
    video-cloud/ssai/all

管理廣告配置

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

列出廣告配置

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

方法 得到
網址 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": "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 }}"
      }
    }
  }
]

建立廣告組態

為帳戶創建廣告配置。

方法 開機自檢
網址 https://ssai.api.brightcove.com/v1/accounts/ 您的帳戶編號/設定
標頭 授權：承載您的訪問令牌
內容類型：應用程序/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": [ "*" ]
  }
}

獲取廣告配置詳細信息

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

方法 得到
網址 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_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更新廣告配置。

方法 放
網址 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": "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 字串 調整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 }}" }
discontinuities.dash[2] [] 字串 控制傳遞多個時期破折號清單的破折號的版本。

設置為["*"]為所有版本提供多週期破折號從不為

空列表

示例：["live-timeline"]為實時時間線提供，但不為 hbbtv 提供
discontinuities.hls[2] [] 字串 控制不連續交付的hls版本。

設置["*"]為在所有版本的 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 字串 信標網址模板
extend_beacon_guard_ttl 布林值 將信標保護TTL的長度（生存時間）設置為內容會話TTL的長度。否則，默認值為1分鐘。

廣告變數

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

系統變量

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

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

欄位 描述
ip_address 一般使用者的 IP 位址
random_number_32 隨機32位整數
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模板之前，先對這些值進行URL編碼。

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

欄位 描述
ad_keys 可以在Video Cloud Studio媒體模塊中添加和編輯的自由格式文本字符串
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中禁用不連續播放。優先於播放配置中的不連續性設置

組態注意事項

  1. 預先載入廣告不應使用 SSAI 進行。原因是，如果您預先載入，播放器將會回報廣告印象，也可能是影片播放前的第一個四分位元信標。這可能會導致不準確的廣告分析。如果您在 Studio 中配置 SSAI，這將自動完成，但如果您碰巧手動設置 SSAI，則需要注意此問題。
  2. 如果網路播放程式使用 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 的廣告錯誤信標文件。