広告設定は、広告コール、ビーコン、その他の設定オプションを含む、SSAI 再生のさまざまな側面を定義します。アカウントは複数の構成を持つことができ、現在の設定はアカウント間で共有できません。

一般情報

以下の情報は、すべての SSAI API リクエストに関連します。

ベース URL

SSAI API のベース URL は次のとおりです。

https://ssai.api.brightcove.com/v1

アカウントパス

いずれの場合も、特定の Video Cloud アカウントに対してリクエストが行われます。したがって、ベース URL には常に、アカウント ID accountsに続く語句を追加します。

https://ssai.api.brightcove.com/v1/accounts/your account id

[認証]

要求の認証には、Authorization ヘッダーが必要です。

Authorization: Bearer your access token

access_tokenは、Brightcove OAuth サービスから取得する必要がある一時的な OAuth2 アクセストークンです。クライアント資格情報を取得し、アクセストークンを取得する方法の詳細については、ブライトコーブ OAuth の概要を参照してください。

オペレーション

クライアントの資格情報を要求するときは、必要なアカウントアクセスの種類または操作を指定する必要があります。以下は、SSAI API に対して現在サポートされている操作の一覧です。

• SSAI データ:

  video-cloud/ssai/read
video-cloud/ssai/all

広告設定の管理

API は、次の GET および PUT リクエストをサポートします。

• 広告構成の一覧表示
• 広告設定を作成する
• 広告構成の詳細を取得する
• 広告設定を更新する

広告構成の一覧表示

アカウントに対して定義された広告設定を一覧表示します。

レスポンスの例:

[
  {
    "name": "VMAP Ad Server",
    "vmap_response_namespace": "bc",
    "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
    "account_id": "57838016001",
    "created_timestamp": "2017-07-24T19:28:34.976878586Z",
    "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
      }
    }
  }
]

広告設定を作成する

アカウントの広告設定を作成します。

サンプル本文:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_config": {
  	"expected_ad_response": "vast_3_0",
  	"disable_server_beacons": false,
    "round_up_cue_points": false,
  	"template_url": {
  		"template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
  	}
  },
  "discontinuities": {
    "hls": [ "*" ]
  }
}

広告設定の詳細を取得する

アカウントの場合、設定 ID で広告設定の詳細を取得します。

レスポンスの例:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
  "account_id": "57838016001",
  "created_timestamp": "2017-07-24T19:28:34.976878586Z",
  "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
  "ad_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
        "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  },
  "beacon_templates": [
      {
        "type": "content_start",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "content_midpoint",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "ad_start",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "content_complete",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      }
    ],
    "discontinuities": {
      "dash": [
        "*"
      ],
      "hls": [
        "*"
      ]
    },
    "extend_beacon_guard_ttl": true
  }
}

広告設定の更新

設定 ID で広告設定を更新します。

{
    "name": "VMAP Ad Server - updated"
}

レスポンスの例:

{
  "name": "VMAP Ad Server - updated",
  "vmap_response_namespace": "bc",
  "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
  "account_id": "57838016001",
  "created_timestamp": "2017-07-24T19:28:34.976878586Z",
  "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
  "ad_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
      "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  }
}

設定フィールドの詳細

この表は、リクエストの本文セクション内で使用される広告設定フィールドを定義します。

広告変数

テンプレート URL内の変数は、変数パスの前後にオプションの空白を含む二重中括弧 ( {{ … }} ) で識別されます。すべての変数には、次の 3 つの名前空間のうちの 1 つが接頭辞が付けられます。

• システム
• url
• メタデータ

システム変数

システム変数は SSAI システムによって提供され、エンドユーザーまたはランダム値を生成するためのヘルパー変数に関する情報です。値は、URL テンプレートに挿入する前に URI エンコードされている必要があります。

システム変数は次のように識別されます。{{system.*}}

URL 変数

エントリポイント vmap/Manifest で提供されるクエリパラメーターは、url名前空間で使用できます。他の名前空間の変数とは異なり、これらのパラメータはテンプレートに挿入するときにURLエンコードされません。変数値は、広告プロバイダに行くURLエンコードする必要がある場合は、エントリポイントURLで二重URLエンコードする必要があります。

URL 変数は次のように識別されます。{{url.*}}

メタデータ変数

メタデータ変数は、Video Cloud データソースと動的配信データソースの両方から派生したコンテンツビデオを表す変数です。値は、URL テンプレートに挿入される前に URL エンコードされます。

メタデータ変数は、次のように識別されます。{{metadata.*}}

エントリポイント URL パラメータ

いくつかの動作を調整するために、SSAI エントリポイント URL（VMAP またはマニフェスト）に追加できるクエリパラメーターがいくつかあります。

構成に関する注意事項

1. 広告のプリロードはSSAIで行うべきではありません。この理由は、プレロードすると、プレーヤーが広告インプレッションを報告し、おそらく動画が再生される前の最初の四分位ビーコンを報告するからです。これにより、広告分析が不正確になる可能性があります。StudioでSSAIを構成すると、これは自動的に行われますが、SSAIを手動でセットアップする場合は、この問題に注意する必要があります。
2. ウェブプレーヤーが SSAI を使用していて、その動機の 1 つが広告ブロッカーを回避することである場合は、サーバーサイドビーコンを使用する必要があります。クライアント側のビーコンはブロックされるため使用しないでください。

クライアント側マクロ

クライアント側の広告マクロを使用する場合は、pageプレフィックスを使用します。これらのマクロを使用すると、VMAP およびサーバーの URL で変数を使用できます。広告マクロの詳細については、広告マクロとserverURL IMA3プラグインドキュメントを使用した広告のセクション。

クライアント側のマクロには、次の接頭辞が付けられます。{{page.*}}

たとえば、DOM document.referrerウィンドウ変数とpageVariable DOM ウィンドウ変数を追加するには、それらの変数にプレフィックスを付けます。page広告テンプレートでは、次のようになります。

https://adserver.com/{{page.document.referrer}}/{{page.pageVariable.whateverIwant}}

プレイバック API document.referrerが返され、VMAP および SRC URL pageVariable.whateverIwantに追加されます。次に、Brightcove Player は、リクエストを送信する前に、クライアント側マクロ置換ロジックを実行し、適切な値を置き換えます。

https://bolt-prefix/blah.vmap?document.referrer={document.referrer}&pageVariable.whateverIwant={pageVariable.whateverIwant}

広告エラービーコン

SSAI を使用する際の VAST 広告エラービーコンは、広告ワークフローに関する問題をプロアクティブに検出して解決するのに役立ちます。詳細については、SSAI を使用した広告エラービーコンのドキュメントを参照してください。