布萊特灣即時 API：服務器端廣告插入 (SSAI)

本主題說明如何為即時串流工作設定伺服器端廣告插入 (SSAI)。

概覽

SSAI允許您在直播活動期間的指定時間展示廣告。主要功能包括：

使用從編碼器發送的提示點插入廣告或使用Live API
內嵌「石板」資產以填滿任何未使用的廣告時間
避免將廣告拼接到伺服器端直播中的廣告攔截器

要使用服務器端廣告創建實時流，請按照以下步驟操作：

查看有關Live API的常規信息
創建實時廣告配置。您也可以在視頻雲工作室 .有關使用Live API管理廣告配置的詳細信息，請參見以下部分。
創建板岩資產。如果您更喜歡 UI，您可以在 Studio 中管理板岩 .
選用性：插入提示點和廣告信標。
現在，您準備好使用 Live API 創建直播流 .如果您更喜歡使用 Studio，您可以在 Live 模塊中實現服務器端廣告

有關使用DFP廣告管理系統和廣告宏的自定義標題，廣告配置變量的詳細信息，請參閱本文檔的其餘部分。

支持地區

以下區域支持 SSAI：

us-west-2
us-east-1
ap-southeast-2
ap-northeast-1
ap-southeast-1
eu-central-1

一般資訊

以下信息與所有帶有SSAI請求的Live API有關。

基本網址

使用SSAI的Live API的基本URL是：

    https://api.bcovlive.io/v1/ssai

驗證

對請求的身份驗證需要帶有API密鑰的標頭：

    X-API-KEY: your API KEY

聯繫您的客戶成功經理以獲取與您的帳戶關聯的 API 密鑰。

建立廣告組態

要創建新的廣告配置，請發送POST要求如下：

方法	`POST`
URL	`https://api.bcovlive.io/v1/ssai/applications`
標頭	`X-API-KEY: your API KEY`

請求主體範例

    {
      "application_ad_configuration": {
        "ad_configuration_compensation_disable": true,
        "ad_configuration_description": "Human readable description of the configuration",
        "ad_configuration_expected_response_type": "Dfp, Vast or SmartXML",
        "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_description": "Human readable description of the ad application",
      "account_id": "User's Account ID [Optional]"
    }

這account_id 字段是真實賬戶 ID。省略時，會使用請求使用者的帳戶 ID。

範例回應

    {
      "application": {
        "account_id": "User Account ID",
        "application_description": "Human readable description of the ad application",
        "application_ad_configuration": {
          "ad_configuration_compensation_disable": true,
          "ad_configuration_description": "Human readable description of the configuration",
          "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
          "ad_configuration_headers": {
            "X-Custom-Header-Rand": "{{random.int32}}",
            "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
          },
          "ad_configuration_headers_for_impressions": false,
          "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
          "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
        },
        "application_id": "Application ID"
      },
      "inserted": true
    }

更新廣告配置

更新廣告配置與創建廣告配置非常相似。做一個PUT要求如下：

方法	`PUT`
URL	`https://api.bcovlive.io/v1/ssai/applications/application/Application_ID`
標頭	`X-API-KEY: your API KEY`

請求主體範例

    {
      "application_ad_configuration": {
        "ad_configuration_description": "Some Updated Description Value",
        "ad_configuration_expected_response_type": "Dfp or Vast or SmartXML,
        "ad_configuration_headers": {
          "X-Custom-Header-Rand": "{{random.int32}}",
          "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse or MultipleAdResponse",
        "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_description": "Human readable description of the ad application",
      "account_id": "User's Account ID [Optional]"
    }

這account_id 字段是真實賬戶 ID。省略時，會使用請求使用者的帳戶 ID。

範例回應

    {
      "account_id": "User Account ID",
      "application_description": "Human readable description of the ad application",
      "application_ad_configuration": {
        "ad_configuration_description": "Some Updated Description Value",
        "ad_configuration_expected_response_type": "Dfp | Vast | SmartXML",
        "ad_configuration_headers": {
        "X-Custom-Header-Rand": "{{random.int32}}",
        "X-VIDEOPLAZA-FORWARDED-FOR": "{{client.ipaddress}}"
        },
        "ad_configuration_headers_for_impressions": false,
        "ad_configuration_strategy": "SingleAdResponse | MultipleAdResponse",
        "ad_configuration_url_format": "https://updated-ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}"
      },
      "application_id": "Application ID"
    }

獲取所有廣告配置

要檢索帳戶的所有廣告配置，請提交GET 要求如下：

方法	`GET`
URL	`https://api.bcovlive.io/v1/ssai/applications/account/Account_ID`
標頭	`X-API-KEY: your API KEY`

這Account_ID這是真實賬戶 ID。

範例回應

    [
      {
        "application_id": "Application_ID_1",
        "application_description": "DFP Single Midroll",
        "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler",
        "ad_configuration_expected_response_type": "Dfp"
        },
        "account_id": "Account_ID"
      },
      {
        "application_id": "Application_ID_2",
        "application_description": "Test DFP Single Midroll"
        "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
        "ad_configuration_expected_response_type": "Dfp"
        },
        "account_id": "Account_ID"
      }
    ]

獲取廣告配置

您還可以通過其檢索特定的廣告配置application_id 通過發送一個GET要求如下：

方法	`GET`
URL	`https://api.bcovlive.io/v1/ssai/applications/application/Application_ID`
標頭	`X-API-KEY: your API KEY`

範例回應

    {
      "application_id": "Application_ID",
      "application_description": "Test DFP Single Midroll",
      "application_ad_configuration": {
        "ad_configuration_description": "DFP Test Config Single Midroll",
        "ad_configuration_strategy": "MultipleAdResponse",
        "ad_configuration_url_format": "https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&ses={{session.session_id}}",
        "ad_configuration_expected_response_type": "Dfp"
      },
      "account_id": "Account_ID"
    }

刪除廣告配置

要刪除廣告配置，請發送DELETE要求如下：

方法	`DELETE`
URL	`https://api.bcovlive.io/v1/ssai/applications/application/APPLICATION_ID`
標頭	`X-API-KEY: your API KEY`

範例回應

    {
    "application_id": "Application_ID",
    "deleted": true
    }

管理板岩

板岩是您自己的資產，用於填充未使用的廣告時間。您可以使用板岩提供“馬上回來”消息或您喜歡的任何內容。

以下是有關添加和管理板岩資產的API請求的詳細信息。

添加板岩資產

要攝取新的平板媒體源資產，請提交POST要求：

方法	`POST`
URL	`https://api.bcovlive.io/v1/ssai/slates`
標頭	`X-API-KEY: your API KEY`

請求主體範例

    {
      "source_url": "https://somesourceasset.com/slate-to-ingest.mp4",
      "account_id": "Account_ID [Optional]",
      "source_description": "User identifiable description for the slate  [Optional]"
    }

這account_id 這是真實賬戶 ID。如果省略，則使用發出請求的用戶的帳戶ID。

範例回應

    {
      "media_source_asset_id": "New_UUID",
      "account_id": "Account_ID",
      "media_source_asset_default": false,
      "media_source_asset_type": "slate",
      "media_source_asset_url": "https://somesourceasset.com/slate-to-ingest.mp4",
      "media_source_asset_status": "transcoding"
      "media_source_asset_description": "User identifiable description for the slate"
    }

注意：該設置media_source_asset_default是不是此時支持。

刪除板岩資產

要刪除平板媒體源資產，請發送DELETE要求：

方法	`DELETE`
URL	`https://api.bcovlive.io/v1/ssai/slates/slate/Slate_MSA_ID`
標頭	`X-API-KEY: your API KEY`

範例回應

    {
      "media_source_asset_id": "MSA_UUID",
      "media_source_asset_type": "slate",
      "media_source_asset_url": "https://someS3urlpath/media.mp4",
      "media_source_asset_default": false,
      "media_source_asset_status": "ready",
      "account_id": "ACCOUNT_ID"
    }

獲取板岩資產

您可以通過發送GET要求：

方法	`GET`
URL	`https://api.bcovlive.io/v1/ssai/slates/account/Account_ID`
標頭	`X-API-KEY: your API KEY`

這Account_ID 這是真實賬戶 ID。

範例回應

    [
      {
      "media_source_asset_id": "MSA_UUID_1",
      "media_source_asset_type": "slate",
      "media_source_asset_default": false,
      "media_source_asset_url": "https://someS3urlpath.com/media.mp4",
      "account_id": "ACCOUNT_ID",
      "media_source_asset_status": "ready"
      },
      {
      "media_source_asset_id": "MSA_UUID_2",
      "media_source_asset_type": "slate",
      "media_source_asset_default": true,
      "media_source_asset_url": "https://someS3urlpath.com/media.mp4",
      "account_id": "ACCOUNT_ID",
      "media_source_asset_status": "ready"
      }
    ]

關於DFP的注意事項

如果您要從DFP廣告管理系統中獲取廣告，請記住以下幾點以防止出現問題。

廣告代碼

當您為 Live 創建廣告代碼時，請確保您遵循正確的指南並包括/live .請參閱 DFP 文檔手動創建主視頻標籤了解詳情。

並發

如果期望大量並發，建議您與DFP客戶小組進行交流。

單個/多個廣告響應

這singleadresponse 和multiadresponse 當前未使用參數SSAI .

居住SSAI只進行一次廣告服務器調用，並期望響應包含中斷的所有廣告，但它將遵循任何必要的廣告包裝器，每個廣告限制為 5 次重定向。可接受以下廣告響應格式，並將其解析如下：

VAST-單一回應或單一回應中的廣告連播
DFP廣告管理系統廣告規則-匯總響應中所有可用的廣告，包括片前，片中，片後定義的廣告
Smart XML-匯總響應中所有可用的廣告，包括片前，片中，片後定義的廣告

廣告請求的自定義標題

這SSAI平台可以通過廣告調用和後端平台使用的所有信標傳遞自定義標頭。某些廣告服務器（例如VideoPlaza）需要自定義標頭。

自定義標頭被指定為一組鍵值對ad_configuration_headers對象，它是application_ad_configuration （見創建廣告配置部分）。

注意事項

默認情況下處理標準頭，例如：
- X-Forwarded-For
- X-Device-User-Agent
標頭值可以使用廣告配置變量
標頭值也可以是靜態字符串

使用廣告宏定位廣告

當你創建廣告配置，您的廣告代碼通常如下所示：

      https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&
      num={{random.int32}}&ses={{session.session_id}}&IDFA={{deviceid}}&
      sitesection={{sitesection}}&breakid={{breakid}}&breaktheme={{breaktheme}}

雙花括號內的項目是變量，也稱為廣告宏，當Brightcove Live發送廣告請求時，它們將替換為值（如果存在）。

可以通過以下方式提供廣告宏值：

使用標題信息
附加網址
動態添加URL
使用手動提示點

使用標題信息

標頭信息，詳見廣告配置變量上面的部分，可用於任何請求。只需在廣告配置中使用適當的鍵名稱指定所需的變量即可。

附加網址

可以將其他會話值附加到直播流的URL，如下所示：

      https://playback.bcovlive.io/e058d9f2737e18/us-west-2/NA/
      playlist.m3u8?deviceid=123456&sitesection=services"

動態添加URL

您可以使用Javascript和Brightcove Player API動態添加URL：

      <!DOCTYPE html>
      <body>
        <video
        id="myPlayerID"
        data-video-id="5975635167001"
        data-account="3737230870001"
        data-player="tIG7lVKBm"
        data-embed="default"
        data-application-id
        class="video-js"
        controls
        width="640"
        height="360"></video>
        <script src="//players.brightcove.net/3737230870001/tIG7lVKBm_default/index.min.js"></script>

        <script type="text/javascript">
        var player = videojs("myPlayerID");

        player.one("loadstart", function(){
          var sourceUrl = player.currentSource();
          console.log(sourceUrl);
          var liveUrlWithParams = sourceUrl.src + "?player_width={width}&player_height={height}&deviceid={deviceid}";

          player.src([{
            "type": "application/vnd.apple.mpegurl",
            "src": liveUrlWithParams
          }]);
        });
      </script>

      </body>

請注意，此示例中的鍵名與上面顯示的廣告代碼中的變量名相對應。

廣告配置變量

廣告配置變量（也稱為信標）可用於請求中以管理廣告配置。有關詳細信息，請參閱實時 API：使用 SSAI 的提示點和廣告信標文檔。

使用手動提示點

特定廣告間隔的值可以與手動提示點插入請求一起發送。有關詳細信息，請參閱實時 API：提示點和廣告信標文檔。

已知問題

SSAI要求實時流視頻具有音軌。
如果返回的VAST具有相同的廣告ID，則即使廣告URL使用動態變量來使其成為唯一URL，服務器也不會請求廣告內容。這確實不是如果您使用 DFP 投放廣告，則適用。
使用DFP廣告管理系統，雖然您可以使用相同的廣告ID，但仍然需要使用其他廣告素材ID-換句話說，您不能簡單地交換MediaFile。
如果廣告間隔的持續時間小於廣告URL的最長持續時間（min_ad_duration = 0＆max_ad_duration = 30000），則如果返回的廣告時間超過了廣告間隔，則該廣告將不會播放。
不支持 VPAID 或可點擊廣告Brightcove Live SSAI .
當廣告間隔的剩餘時間短於流的片段秒數並顯示一個石板時，將顯示該石板的片段持續時間，並且實際的廣告間隔將比預期的長。
上述情況可能會導致以下廣告中斷之一被延遲時間縮短，以嘗試使會話恢復到實時邊緣。
我們的系統第一次看到廣告時，直到廣告轉碼並準備好發送後才會播放。
當前不支持Live SSAI的VMAP。