Brightcove Live API：サーバーサイド広告挿入（SSAI）

このトピックでは、ライブストリームジョブのサーバー側広告挿入（SSAI）を設定する方法を示します。

概要

SSAIライブストリーミングイベント中に指定した時間に広告を表示できます。主な機能は次のとおりです。

エンコーダから送信されたキューポイントを使用して広告を挿入するか、を使用してインスタントキューポイントを作成しますライブAPI
「スレート」アセットを取り込み、未使用の広告時間を埋める
サーバー側のライブストリームに縫い付けられた広告で広告ブロッカーを避ける

サーバーサイド広告でライブストリームを作成するには、次の手順に従います。

Live API に関する一般的な情報を確認します
ライブ広告の設定を作成します。これは、ビデオクラウドスタジオでも行うことができます。Live API を使用した広告設定の管理の詳細については、以下のセクションを参照してください。
スレートアセットを作成します。UI を使用する場合は、 Studio でスレートを管理できます。
オプション:キューポイントと広告ビーコンを挿入します。
これで、ライブ API を使用してライブストリームを作成する準備ができました。Studio を使用する場合は、 Live モジュールでサーバーサイド広告を実装できます。

DFP と広告マクロを使用したカスタムヘッダー、広告設定変数の詳細については、このドキュメントの残りの部分を参照してください。

一般情報

以下の情報は、すべてのライブAPIとSSAIリクエストに関するものです。

ベース URL

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

NS account_id フィールドはライブアカウントIDです。省略した場合、要求元ユーザーのアカウントIDが使用されます。

レスポンスの例

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

NS 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_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`

NS 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_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 リクエストの詳細を示します。

スレートアセットを追加する

新しいスレートメディアソースアセットを取り込むには、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]"
    }

NS 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": "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`

NS Account_ID これがライブアカウントIDです。

レスポンスの例

    [
      {
      "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 。詳細については、DFP ドキュメントの「マスタービデオタグを手動で作成する」を参照してください。

同時実行性

同時実行性が高いことが予想される場合は、DFP アカウントチームにご相談いただくことをお勧めします。

単一/複数広告の回答

NS singleadresponse とmultiadresponse パラメータは現在、によって使用されていませんSSAI。

住むSSAI単一の広告サーバー呼び出しのみを行い、応答には、広告ごとに5リダイレクトの制限がある必要な広告ラッパーに従うことを除いて、休憩のすべての広告が含まれることを期待します。次の広告回答形式が受け入れられ、次のように解析されます。

VAST-単一のレスポンス、または単一のレスポンスで広告ポッドを表示
DFP 広告ルール-プレロール、ミッドロール、ポストロール定義広告を含む、利用可能なすべての広告をレスポンスに集約します。
Smart XML-事前定義、ミッドロール、ポストロール定義広告を含む、利用可能なすべての広告をレスポンスに集約します。

広告リクエストのカスタムヘッダー

NS SSAIプラットフォームは、バックエンドプラットフォームで使用される広告呼び出しとすべてのビーコンでカスタムヘッダーを渡すことができます。VideoPlaza などの一部の広告サーバーには、カスタムヘッダーが必要です。

カスタムヘッダーは、ad_configuration_headersオブジェクト内のキーと値のペアのセットとして指定されますapplication_ad_configuration （Create を参照）。広告設定セクション)。

注

標準ヘッダーは、次のようにデフォルトで処理されます。
- 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ライブでは、広告リクエストを送信するときに、値が置き換えられます（存在する場合）。

広告マクロの値は、次の方法で指定できます。

ヘッダー情報の使用
URLの追加
URL を動的に追加する
手動キューポイントの使用

ヘッダー情報の使用

上記の [ 広告設定変数 ] セクションに詳述されているヘッダー情報は、どのリクエストでも使用できます。広告設定で、必要な変数を適切なキー名で指定するだけです。

URLの追加

ライブストリームの 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>

この例のキー名は、上記の広告タグの変数名に対応していることに注意してください。

広告の設定変数

広告設定変数（ビーコンとも呼ばれます）は、広告設定を管理するためのリクエストで使用できます。詳細については、Live API を参照してください。キューポイントと広告ビーコン（SSAI ドキュメント）

手動キューポイントの使用

特定の広告ブレークの値は、手動キューポイント挿入リクエストで送信できます。詳細については、Live API を参照してください。キューポイントと広告ビーコンドキュメント。

既知の問題

SSAI では、ライブストリーミングビデオにオーディオトラックが必要です。
返された VAST が同じ広告 ID を持つ場合、広告 URL が動的変数を使用して一意の URL にする場合でも、サーバーは広告コンテンツを要求しません。これは、広告に DFP を使用している場合は適用されません。
DFP では、同じ広告 ID を使用できますが、別のクリエイティブ ID が必要です。つまり、MediaFile を単純にスワップすることはできません。
広告区切りの期間が、広告 URL の最大継続時間（min_ad_duration=0&max_ad_duration=3000）よりも短い場合、広告が広告区切りよりも長く返された場合、広告は再生されません。
VPAIDまたはクリック可能な広告はサポートされていませんブライトコーブライブSSAI。
広告ブレークの残り時間がストリームのセグメント秒より短く、スレートが表示されると、そのセグメント期間中はスレートが表示され、実際の広告ブレークは予想よりも長くなります。
上記の原因により、セッションをライブエッジに戻そうとするために、次の広告ブレークのいずれかが遅延時間によって縮小される可能性があります。
Google のシステムで初めて広告が表示された場合は、トランスコードされて配信する準備が整うまで再生されません。
Live SSAI 用の VMAP は現在サポートされていません。

ページコンテンツ

Brightcove Live API：サーバーサイド広告挿入（SSAI）

概要

一般情報

ベース URL

認証

広告設定を作成する

リクエスト本文の例

レスポンスの例

広告設定の更新

リクエスト本文の例

レスポンスの例

すべての広告設定を取得する

レスポンスの例

広告設定を取得する

レスポンスの例

広告設定の削除

レスポンスの例

スレートの管理

スレートアセットを追加する

リクエスト本文の例

レスポンスの例

スレートアセットを削除

レスポンスの例

スレート資産を手に入れよう

レスポンスの例

DFP に関する注意事項

広告タグ

同時実行性

単一/複数広告の回答

広告リクエストのカスタムヘッダー

注

広告マクロを使用して広告をターゲティングする

ヘッダー情報の使用

URLの追加

URL を動的に追加する

広告の設定変数

手動キューポイントの使用

既知の問題