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

即時 API：提示點和廣告信標與 SSAI

在本主題中，您將學習如何在使用 Brightcove 的伺服器端廣告插入 (SSAI) 進行即時串流工作時，如何管理提示點和廣告信標。

概覽

服務器端廣告插入(SSAI)允許您在直播事件期間的指定時間展示廣告。有關一般信息，請參見實時API：服務器端廣告插入(SSAI)文件。

提示點

廣告休息時間由提示點觸發，可以通過兩種方式指定：

  • 編碼器發送給Brightcove
  • 通過創建即時提示點Live API

從編碼器

Brightcove實時投放系統可以解釋編碼器以AMF格式提交的提示點：

  AMFDataList
  [0]:onCuePoint
  [1]:{Obj[]:
    time: 1.9889, //Difference from PTS of THIS packet to the first PTS of the 1st video frame in the adbreak
    name: "scte35",
    type: "event",
    ad_server_data: "YWJjZGVmZ2g=",	// optional introduced by Brightcove. It is a base64 encoded json map of parameters e.g. {‘key’:’value’}
    parameters: {Obj[]:
      type: "avail_in",
      duration: 12.0
    }
  }

注意事項：

  • RTMP 輸入目前僅支援avail_in類型提示點。
  • RTP 和 SRT 輸入支持 SCTE-35 提示點。

手動插入提示點

您可以使用創建即時提示點Live API通過發送一個POST請求：

方法 POST
URL https://api.bcovlive.io/v1/jobs/Job_ID/cuepoint
標頭 X-API-KEY: your API KEY

包括指定以下內容的請求正文：

欄位 類型 描述
duration 整數 休息時間（以秒為單位）。

插入提示點的持續時間需要為至少是段長度的兩倍就職（於）;著手（於。見持續時間的例子。
timecode SMPTE格式 選用性：SMPTE格式的時間碼， HH：MM：SS：FF（FF =幀），以指定何時應將一組任何變量（鍵/值對）傳遞給adServer。

如果省略，提示點將立即插入。

如果您使用timecode屬性，則編碼器必鬚髮送SMPTE格式的（HH:MM:SS:FF）存儲在tc通過屬性OnFI。時間碼是從直播開始的。
ad_server_data 物件 選用性：您傳遞的鍵/值對將取決於您使用的廣告服務器。有關更多詳細信息，請參見廣告服務器文檔和使用廣告宏定位廣告部分。

持續時間示例

插入提示點的持續時間需要為至少是段長度的兩倍就職（於）;著手（於。

例如，插入一個10秒提示點在工作中"segment_seconds"=4，可以正常工作。但是，在作業中插入相同的提示點"segment_seconds"=6將導致以下錯誤：

  "error": "The parameter duration should be greater than
    or equal to (2 * target duration) of the job"
 

請求主體範例

  {
    "duration": 30,
    "timecode": "15:50:49:16",
    "ad_server_data" : {
    "adbreakid": 12312
    "breaktheme": "fitness"
    }
  }

注意事項

  1. Wirecast和OBS等軟件編碼器不支持通過以下方式發送時間代碼OnFI RTMP流中的數據包
  2. 基本硬件編碼器確實支持通過以下方式發送時間代碼OnFI RTMP流中的數據包

範例回應

  {
    "id": "Job_ID",
    "cue_point": {
      "id": "adBreak-2f58393ada1442d98eca0817fa565ba4",
      "duration": 30,
      "accuracy": "segment", [Can be segment or frame  ]
      "inserted_at": "2017-07-21T09:30:46.307Z" [ Time when the cue point was inserted in the stream]
    },
  }

信標

信標是發送到第三方分析的回放數據點，以跟踪是否播放了廣告以及播放了多少廣告。在本節中，我們將討論可以使用以下命令設置的信標類型Live API以及可用於提供數據的變量。下一部分將詳細介紹用於創建和管理信標集的API請求。

信標類型

信標類型
信標類型 描述
Load 每個會話觸發一次，僅在請求頂級清單時觸發
Play 已請求內容，並且返回了第一段
Heartbeat 目標持續時間（段秒）
AdStart 個別廣告已開始
AdFirstQuartile 前四分位（25％）
AdMidpoint 廣告四分位數（50％）
AdThirdQuartile 第三四分位（75％）
AdComplete 個別廣告已完成
AdBreakStart 廣告中斷已開始
AdBreakComplete 廣告中斷已結束

信標/廣告變量

下表顯示了可用於為信標URL提供數據的變量。要包含變量，請用雙大括號括起來，如下所示：{{job.job_id}} 。有關完整的示例，請參見下一部分有關管理信標集的部分。

廣告配置變量
變數
描述
session.session_id
唯一的會話ID
job.job_id
唯一的工作ID
videocloud.video_id
僅適用於使用VideoCloud視頻創建的作業。
application_ad_configuration.description
會話創建時應用程序的價值
random.int32
隨機的32位有符號整數
random.int64
隨機的64位有符號整數
random.uint32
隨機32位無符號整數
random.uint64
隨機的64位無符號整數
random.uuid
隨機uuid
server.timestamputc
調用ads-api的時間間隔（以毫秒為單位）
client.useragent
會話創建時的http用戶代理標頭值
client.ipaddress
會話創建時的http x-forwarded-for標頭值（如果提供），否則為遠程地址
client.referrer
會話創建時的http Referer標頭值（注意：這是正確的拼寫）
client.referer
會話創建時的http Referer標頭值（http拼寫）
client.ipuaid
client.ipaddress和client.useragent的哈希值
live.adbreak
（當前未使用）
live.adbreakdurationms
廣告休息時間（以毫秒為單位）
live.adbreakduration
廣告中斷持續時間（以雙精度浮點秒為單位）
live.adbreakdurationint
廣告休息時間（以整數秒為單位）
live.adbreak.timestamputc.wallclock
調用廣告服務器的時間間隔（以毫秒為單位）
live.adbreak.timestamputc.origin
從原始塊列表開始的時間（以毫秒為單位）。該值指示在原始塊列表中創建提示塊的時間。
live.adbreak.timestamputc.session
ssai塊列表中的時間間隔（以毫秒為單位）。此值指示ssai塊列表中提示塊的時間。由於adbreak內容和adbreak間隙通常不相同，因此在第1次adbreak之後，live.adbreak.timestamputc.origin 與...不同live.adbreak.timestamputc.session 。該值考慮了在SSAI塊列表。

SCTE-35廣告變量

的電纜電信工程師協會（SCTE）定義了用於實時流的動態廣告插入的標準。下表總結了SCTE-35廣告配置變量。

SCTE-35廣告配置變量
變數
描述
scte35_eventID
隨SCTE35消息傳遞的唯一事件ID。
scte35_programID
隨SCTE35消息傳遞的唯一程序ID。
scte35_availNum
廣告可用的特定拼接時間的ID，通過SCTE35消息發送。
scte35_breakDuration
廣告中斷的中斷時間（以程序的90 kHz時鐘的滴答度表示）隨SCTE35消息傳遞。
scte35_spliceTime
廣告中斷的拼接時間（以程序的90 kHz時鐘的滴答度表示）隨SCTE35消息一起傳遞。

管理信標集

本節提供有關管理信標集的API請求的詳細信息。有關信標類型和變量，請參見上一節。

要將信標集添加到實時作業中，請先創建信標集，然後在創建作業時添加標識，如下所示：

  {
  "live_stream": true,
  "region": "us-west-2",
  "reconnect_time": 30,
  "ad_insertion": true,
  "beacon_set": "beacon_set_id", ...

創建信標集

要創建信標集，請發送一個POST請求：

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

請求主體範例

  {
    "account_id": "User's Account ID [Optional]",
    "beacon_urls": [
      {
        "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Load"
      },
      {
        "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
        "beacon_type": "Play"
      }
    ]
  }

範例回應

  {
    "beacon_set": {
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/load?position=load&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
      "beacon_type": "Load"
    },
    {
      "beacon_url": "https://myserver.com/beaconRX/{{job.job_id}}/play?position=play&sid={{session.session_id}}&jid={{job.job_id}}&app={{application_ad_configuration.description}}&rnd32={{random.int32}}&rnd64={{random.int64}}&bid={{random.uuid}}&t={{server.timestamputc}}&ua={{client.useragent}}&ip={{client.ipaddress}}&ref={{client.referrer}}&ref={{client.referer}}&ab={{live.adbreak}}&abd={{live.adbreakduration}}&abdi={{live.adbreakdurationint}}",
      "beacon_type": "Play"
    }],
    "beacon_set_id": "Inserted Beacon Set ID",
    "account_id": "USER's ACCOUNT ID"
    }
    "inserted": true
  }

更新信標集

更新信標集與創建信標集相似。提交一個PUT請求：

方法 PUT
URL https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id
標頭 X-API-KEY: your API KEY

請求主體範例

  {
    "account_id": "User's Account ID [Optional]",
    "beacon_urls": [
      {
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX/play",
      "beacon_type": "Play"
      }
    ]
  }

範例回應

  {
    "beacon_set": {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID",
      "beacon_urls": [{
        "beacon_url": "https://myserver.com/beaconRX/load",
        "beacon_type": "Load"
        },
        {
        "beacon_url": "https://myserver.com/beaconRX/play",
        "beacon_type": "Play"
      }],
      "updated_beacon_set": {
        "beacon_set_id": "Beacon set ID",
        "beacon_urls": [{
          "beacon_url": "https://myserver.com/beaconRX/load",
          "beacon_type": "Load"
        },
        {
          "beacon_url": "https://myserver.com/beaconRX/play",
          "beacon_type": "Play"
        }],
        "account_id": "User's Account ID"
      }
    }
  }

獲取信標集

要檢索帳戶的信標集，請提交一個GET請求：

方法 GET
URL https://api.bcovlive.io/v1/ssai/beaconsets/account/Account ID
標頭 X-API-KEY: your API KEY

範例回應

  [{
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID1",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
    }]
    },
    {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID2",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX2/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX2/play",
      "beacon_type": "Play"
      }]
  }]

獲取請求用戶的信標集

您還可以獲取請求用戶帳戶的信標集，而無需在請求URL中包含帳戶ID：

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

範例回應

  [{
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID1",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX/load",
      "beacon_type": "Load"
    }]
    },
    {
      "account_id": "User's Account ID",
      "beacon_set_id": "Beacon set ID2",
      "beacon_urls": [{
      "beacon_url": "https://myserver.com/beaconRX2/load",
      "beacon_type": "Load"
      },
      {
      "beacon_url": "https://myserver.com/beaconRX2/play",
      "beacon_type": "Play"
      }]
  }]

獲取ID設置的信標

要通過其ID檢索單個信標集，請提交一個GET請求：

方法 GET
URL https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id
標頭 X-API-KEY: your API KEY

範例回應

  {
      "account_id": "User account ID",
      "beacon_set_id": "Beacon set ID",
      "beacon_urls": [{
        "beacon_type": "Load",
        "beacon_url": "https://myserver.com/beaconRX2/load"
    },
    {
      "beacon_type": "Play",
      "beacon_url": "https://myserver.com/beaconRX2/play"
    }]
  }

刪除信標集

最後，要刪除信標集，請發送一個DELETE請求：

方法 DELETE
URL https://api.bcovlive.io/v1/ssai/beaconsets/beaconset/beacon_set_id
標頭 X-API-KEY: your API KEY

範例回應

響應將如下所示：

  {
    "beacon_set_id": "Beacon set ID",
    "deleted": true
  }

附錄

下面的屏幕截圖顯示了Elemental編碼器的示例提示點設置。

元素提示點設置
元素提示點設置