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

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

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

概覽

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

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

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

  1. 查看有關Live API的常規信息
  2. 創建實時廣告配置。您也可以在Video Cloud Studio。有關使用Live API管理廣告配置的詳細信息，請參見以下部分。
  3. 創建板岩資產。如果您喜歡UI，可以在Studio中管理板岩。
  4. 選用性：插入提示點和廣告信標。
  5. 現在，您準備好了使用Live API創建實時流。如果您想使用Studio，可以在實時模塊中實施服務器端廣告

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

一般資訊

以下信息與所有帶有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_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_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "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]"
    }

範例回應

    {
      "application": {
        "account_id": "User Account ID",
        "application_description": "Human readable description of the ad application",
        "application_ad_configuration": {
          "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_transforms": [
            {
              "xpath": "/",
              "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
            }
          ],
          "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_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "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": "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_transforms": [
          {
          "xpath": "/",
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>"
          }
        ],
        "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

範例回應

    [
      {
        "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_transforms": [],
        "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_transforms": [
        {
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
          "xpath": "/"
        }
        ],
        "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_transforms": [
          {
          "xslt": "<xsl:stylesheet version=\"1.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\" xmlns:Det=\"http://Det.com\"><xsl:output omit-xml-declaration=\"yes\"/><xsl:template match=\"node()|@*\"><xsl:copy><xsl:apply-templates select=\"node()|@*\"/></xsl:copy></xsl:template></xsl:stylesheet>",
          "xpath": "/"
          }
        ],
        "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請求的詳細信息。

添加板岩資產

要提取新的slate媒體源資產，請提交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]"
    }

範例回應

    {
      "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"
    }

刪除板岩資產

要刪除平板媒體資源，請發送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": "http://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

範例回應

    [
      {
      "media_source_asset_id": "MSA_UUID_1",
      "media_source_asset_type": "slate",
      "media_source_asset_default": false,
      "media_source_asset_url": "http://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": "http://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，如下所示：

      http://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。