サポートに連絡する| システムステータス
ページコンテンツ

    このページは移動しました。3 秒後に新しい場所に移動します。ブックマークを更新してください!

    Live API:SSAI

    付きキューポイントと広告ビーコン:このトピックでは、ライブストリームジョブにBrightcoveのサーバー側広告挿入(SSAI)を使用するときにキューポイントと広告ビーコンを管理する方法を学習します。

    概要

    サーバーサイド広告挿入(SSAI)を使用すると、ライブストリーミングイベント中に指定した時間に広告を表示できます。一般的な情報については、 Live API を参照してください。サーバーサイド広告挿入 (SSAI) ドキュメント。

    キューポイント

    広告ブレークはキューポイントによってトリガーされます。キューポイントは次の 2 つの方法で指定できます。

    • エンコーダによってBrightcoveに送信
    • ライブ API を介して作成された即時のキューポイント

    エンコーダから

    ブライトコーブのライブ配信システムは、エンコーダによって送信されたキューポイントを 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タイプキューポイントのみがサポートされています。
    • SCTE-35キューポイントは、RTPおよびSRT入力でサポートされています。

    キューポイントの手動挿入

    Live API POSTを使用してリクエストを送信することで、即時のキューポイントを作成できます。

    方法 POST
    URL https://api.bcovlive.io/v1/jobs/Job_ID/cuepoint
    ヘッダー X-API-KEY: your API KEY

    以下を指定するリクエスト本文を含めます。

    フィールド タイプ 説明
    duration 整数 休憩時間(秒)。

    挿入されるキューポイントのデュレーションは、ジョブ内のセグメントの長さの少なくとも 2 倍にする必要があります。デュレーションの例を参照してください
    timecode SMPTEフォーマット オプション:SMPTE 形式のタイムコード、 HH: MM: SS: FF (FF = フレーム)。一連の変数(キーと値のペア)を AdServer に渡すタイミングを指定します。

    省略した場合、キューポイントはすぐに挿入されます。

    タイムコードプロパティを使用する場合、エンコーダーはSMPTE形式(HH:MM:SS:FF)に保存されているタイムコードtcプロパティ経由OnFI。タイムコードは、ライブストリームの先頭からのものです。
    ad_server_data オブジェクト オプション:渡すキー/値のペアは、使用している広告サーバーによって異なります。詳細については、広告サーバーのドキュメントおよび「広告マクロを使用した広告のターゲティング」セクションを参照してください。

    デュレーションの例

    挿入されるキューポイントのデュレーションは、ジョブ内のセグメントの長さの少なくとも 2 倍にする必要があります。

    たとえば、 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 などのソフトウェアエンコーダは、RTMP OnFIストリーム内のパケットを介した送信タイムコードをサポートしていません。
    2. Elemental ハードウェアエンコーダは、RTMP OnFIストリーム内のパケットを介した送信タイムコードをサポートしています。

    レスポンスの例

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

    ビーコン

    ビーコンは、再生時にサードパーティアナリティクスに送信されるデータポイントで、再生された広告の有無と量を追跡します。このセクションでは、ライブ API を使用して設定できるビーコンタイプと、データの提供に使用できる変数について説明します。次のセクションでは、ビーコンセットの作成と管理に使用する API リクエストについて詳しく説明します。

    ビーコンの種類

    ビーコンの種類
    ビーコンタイプ 説明
    Load セッションごとに 1 回発生し、トップレベルのマニフェストがリクエストされたときにのみトリガーされます。
    Play コンテンツが要求され、最初のセグメントが返されました
    Heartbeat 目標期間(セグメント秒)
    AdStart 個人広告開始しました
    AdFirstQuartile 第1および四分位数 (25%)
    AdMidpoint 第二四分位数 (50%)
    AdThirdQuartile 第3および四分位数 (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リファラーヘッダー値(注:正しい綴りです)
    client.referer
    セッション作成時のHTTPリファラーヘッダー値(http綴り)
    client.ipuaid
    クライアント.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 チャンクリストのキューアウトチャンクの時間を示します。アドブレークの内容とアドブレイクギャップは通常同じではないので、live.adbreak.timestamputc.origin 第1アドブレイク以降はとは異なります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
    SCTE35 メッセージで渡されたプログラムの 90 kHz クロックのティックに関して、広告休憩の休憩時間。
    scte35_spliceTime
    SCTE35 メッセージで渡されたプログラムの 90 kHz クロックのティックに関して、広告休憩のスプライスタイム。

    ビーコンセットの管理

    このセクションでは、ビーコンセットを管理するための API リクエストの詳細を示します。ビーコンの種類と変数については、前のセクションを参照してください。

    ライブジョブにビーコンセットを追加するには、まずビーコンセットを作成し、次にジョブの作成時に ID を含めます。

      {
      "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 エンコーダのキューポイント設定のサンプルを示すスクリーンショットを示します。

    Elemental Cue Point Setup
    エレメントキューポイントのセットアップ

    ページの最終更新日30 Sep 2021