DAI ライブ配信を管理する

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

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

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

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

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

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

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":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

エラー レスポンス

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

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

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

2. 新しい AdBreak メタデータをポーリングする

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

帯域幅を最適化するには、次の操作を行います。

  1. metadata_url エンドポイントに最初の GET リクエストを送信します。
    • delta_token クエリ パラメータを省略します。このプロセスにより、サーバーはストリームのデジタル ビデオ レコーダー（DVR）ウィンドウの完全なメタデータを返すことができます。DVR ウィンドウには、視聴者が巻き戻して再生できる放送の時間枠が含まれます。レスポンスには next_delta_token オブジェクト フィールドが含まれます。
  2. メタデータをクライアントサイドに保存します。
  3. 最新のレスポンスが返す next_delta_token 値を使用して、後続の呼び出しを行います。各レスポンスには next_delta_token 値が含まれます。常に受け取った最新の値を送信します。
  4. 保存されているメタデータを更新して、変更を統合し、古い広告ブレークを削除します。

差分トークンの解析、構築、変更は行わないでください。トークンの形式は変更される可能性があります。受け取ったトークンを保存し、次のリクエストで変更せずにトークンを返します。

初期リクエストの例

初回リクエストではクエリ パラメータは使用されず、完全なメタデータが返されます。

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

後続のリクエストの例

以降の各リクエストでは、前のレスポンスの next_delta_token 値が delta_token パラメータとして渡されます。レスポンスには次のものが含まれます。

  • 広告
  • ミッドロール挿入点
  • サーバーがトークンを発行してからサーバーが追加または更新したタグ。
  • 保存されたメタデータから削除する広告ブレークの obsolete_ad_break_ids リスト

サーバーは変更されていない広告ブレークを省略します。次の例は、デルタ トークンを使用して、これらの最近の変更のみを取得する後続のポーリングを示しています。

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

成功すると、次のような出力が表示されます。

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. ID3 イベントをリッスンし、再生イベントをトラッキングする

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

  1. メディア イベントをキューに保存し、各メディア ID をタイムスタンプとともに保存します（プレーヤーによって表示される場合）。
  2. プレーヤーからの時間更新ごと、または設定された頻度（500 ミリ秒を推奨）で、イベントのタイムスタンプと再生ヘッドを比較して、最近再生されたイベントのメディア イベント キューを確認します。
  3. 再生されたことを確認したメディア イベントについては、保存されているミッドロール挿入点タグでメディア ID を調べてタイプを確認します。保存されたタグにはメディア ID の接頭辞のみが含まれるため、完全一致はできません。
  4. 動画プレーヤー アプリはメタデータ URL を定期的にポーリングするため、動画プレーヤーがストリーム内の ID3 タグを検出してから、関連するメタデータが利用可能になるまでに遅延が発生する可能性があります。保存されたタグに ID3 タグが見つからない場合は、タグをキューに保持し、次のメタデータ ポーリング後にタグを再処理します。処理が完了するまで、イベントをキューに保持します。
  5. メタデータでタグを見つけたら、タグの type フィールドを次のセクションに記載されている広告イベント タイプと照合します。動画プレーヤーがミッドロール挿入点を再生しているかどうかを追跡するには、type フィールドの値が progress のイベントを使用します。これらのイベントをメディア検証エンドポイントに送信しないでください。他のすべてのイベントタイプでは、メディア ID をメディア検証エンドポイントに追加し、GET リクエストを行って再生をトラッキングします。
  6. メディア イベントをキューから削除します。

広告イベントタイプ

メタデータ tags オブジェクトの各タグには、次のいずれかのイベントタイプがあります。

イベントの種類 説明
start 広告の開始時に実行されます。
firstquartile 広告の最初の 4 分の 1 の終了時に実行されます。
midpoint 広告の中間地点で実行されます。
thirdquartile 広告の第 3 四分位の終了時に実行されます。
complete 広告の終了時に実行されます。
progress 広告ブレーク中に定期的に実行され、広告ブレークが再生中であることを通知します。これらのイベントをメディア検証エンドポイントに送信しないでください。

リクエスト例

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

返信の例

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/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/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 を送信することを防ぐための設計です。

参考情報