即時 API：使用 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: "eyJrZXkiOiJ2YWx1ZSJ9",	// 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
    }
  }

注意事項：

• 由於時間碼以 HH:MM:SS 表示，因此沒有日期的概念。這可能會導致問題，例如在 23:55:00 發送提示點以讓廣告中斷從 00:01:00 開始，並讓服務器將其解釋為將近 24 小時前。Brightcove 已為此實施瞭如下修復：對於 僅在 23:50:00 和 00:00:00 之間到達的提示點，我們假設您正在安排第二天的廣告時段。
• 單個請求中最多可堆疊 128 個提示點，但考慮到上述關於“滾動”的規則，第二天不能以這種方式發送提示點。
• 由於 SMPTE 時間碼與流相關聯，因此提示可能會在流中的預定時間之後到達。Brightcove 將在提示後允許最多 5 秒的容差以仍然插入提示點。
• 僅有的avail_in和avail_out RTMP 輸入目前支持類型提示點。
• RTP 和 SRT 輸入支持 SCTE-35 提示點。

手動插入提示點

您可以使用Live API通過發送一個POST要求：

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

持續時間示例

插入的提示點的持續時間需要至少是片段長度的兩倍在工作。

例如，插入一個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. Elemental 硬件編碼器確實支持通過以下方式發送時間碼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請求。

信標類型

信標/廣告變量

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

SCTE-35廣告變量

這有線電信工程師協會 (SCTE)定義了實時流的動態廣告插入標準。SCTE-35 廣告標記定義可將廣告插入流中的時間戳和持續時間。

如果從 SCTE-35 解析，則可以將以下配置變量應用於您的廣告代碼：

作為 HLS 清單的一部分，SCTE-35 消息也是帶有 JSON 變量的 base64。例如：

{"scte35_eventID": somevalue, "scte35_programID": somevalue}

管理信標集

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

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

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

創建信標集

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

請求主體範例

{
    "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要求：

請求主體範例

{
    "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要求：

範例回應

[{
      "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：

範例回應

[{
      "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要求：

範例回應

{
      "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要求：

範例回應

響應將如下所示：

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

附錄

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