ライブ ストリーム用のダイナミック広告挿入 API

Google DAI API を使用すると、IMA SDK の実装がサポートされていない環境で Google DAI 対応ストリームを実装できます。IMA SDK がサポートされているプラットフォームでは IMA を使用することをおすすめします。

DAI API は、次のプラットフォームで使用することをおすすめします。

  • Samsung スマートテレビ（Tizen）
  • LG テレビ
  • HbbTV
  • Xbox（JavaScript アプリ）
  • KaiOS

この API は、IMA DAI SDK の基本的な機能をサポートしています。互換性やサポートされている機能について具体的な質問がある場合は、Google アカウント マネージャーにお問い合わせください。

ライブ ストリーム用の DAI API を実装する

DAI API は、HLS プロトコルと DASH プロトコルの両方を使用するリニア（LIVE）ストリームをサポートしています。このガイドで説明する手順は、両方のプロトコルに適用されます。

ライブ ストリーム用のアプリに API を統合する手順は次のとおりです。

1. ストリームをリクエストする

DAI API からライブ配信をリクエストするには、ストリーム エンドポイントに対して POST 呼び出しを行います。JSON レスポンスには、ストリーム マニフェストと、関連する DAI API エンドポイントと値が含まれます。

リクエスト本文の例

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

レスポンス本文の例

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

エラー レスポンス

エラーが発生した場合は、標準の HTTP エラーコードが JSON レスポンスの本文なしで返されます。

JSON レスポンスを解析し、次の値を保存します。

stream_id
この値は、返されるストリームを識別するために使用できます。
stream_manifest
この URL は、ストリーム再生のためにメディア プレーヤーに渡されます。
media_verification_url
この URL は、再生イベントをトラッキングするためのベース エンドポイントです。
metadata_url
この URL は、今後のストリーム イベントに関する定期的な情報をポーリングするために使用されます。
session_update_url
この URL は、最初のストリーム リクエスト中に送信されたストリーム リクエスト パラメータを更新するために使用されます。このリクエストのパラメータは、以前のストリームに設定されたすべてのパラメータを置き換えます。
polling_frequency
更新された AdBreak メタデータを DAI API からリクエストする頻度（秒）。

2. 新しい AdBreak メタデータのポーリング

メタデータ URL を使用して、ポーリング頻度で新しい AdBreak メタデータをポーリングするタイマーを設定します。ストリーム レスポンスで指定されていない場合、デフォルトの推奨間隔は 10 秒です。

リクエスト本文の例

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

レスポンス本文の例

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. ID3 イベントをリッスンし、再生イベントを追跡する

動画ストリームで特定のイベントが発生したことを確認するには、次の手順で ID3 イベントを処理します。

  1. メディア イベントをキューに格納し、各メディア ID とそのタイムスタンプ（プレーヤーで表示される場合）を保存します。
  2. プレーヤーで更新されるたびに、または設定した頻度（推奨: 500 ミリ秒）で、イベントのタイムスタンプとプレイヘッドを比較して、メディア イベント キューで最近再生されたイベントを確認します。
  3. 再生したメディア イベントについては、保存されているミッドロール挿入点タグでメディア ID を検索して、タイプを確認します。格納されるタグにはメディア ID の接頭辞のみが含まれるため、完全一致は不可能です。
  4. 「progress」イベントを使用して、ユーザーがミッドロール挿入点にいるかどうかを追跡します。 これらのイベントをメディア確認エンドポイントに送信しないでください。他のイベントタイプの場合は、メディア ID をメディア検証エンドポイントに追加し、再生をトラッキングするための GET リクエストを送信します。
  5. キューからメディア イベントを削除します。

リクエスト本文の例

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

回答例

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

トラッキング イベントは、ストリーム アクティビティ モニターで確認できます。

4. ライブストリーム セッションのパラメータを更新する

ストリームの作成後にセッション パラメータを調整できます。そのためには、セッション更新 URL にリクエストを行います。

リクエスト本文の例

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

レスポンス本文の例

Successful response would be to look for - HTTP/1.1 200

制限事項

WebView 内で API を使用する場合、ターゲティングに関して次の制限が適用されます。

  • UserAgent: ユーザー エージェント パラメータは、基になるプラットフォームではなくブラウザ固有の値として渡されます。
  • rdid、idtype、is_lat: デバイス ID が適切に渡されないため、次の機能が制限されます。
    • フリークエンシー キャップ
    • 順次広告のローテーション
    • オーディエンス セグメンテーションとターゲティング

ベスト プラクティス

ライブストリーム インデックスのメタデータ エンドポイントは、対応する ID3 タグのプレフィックスに基づいています。これは、すべての検証ノードに即座に ping が送信されることを避けるために、メタデータ エンドポイントが使用されないようにするためです。

補足資料