カスタム インテグレーションを使用する

始める前に

このドキュメントでは、IMA DAI SDK を使用しない再生手順のみについて説明します。

事前に Google アド マネージャー（GAM）と VOD アセットを統合するの手順を完了していることを確認してください。

注: IMA DAI SDK がサポートされているプラットフォームでは、使用することを強くおすすめします。

目的のプラットフォームで IMA SDK を使用できない場合は、アプリケーションで必要な API を呼び出し、広告メディアの検証自体をトリガーする必要があります。

このためには、次の情報が必要です。

ロケーション	ライブ構成が作成された Google Cloud リージョン : LOCATION
プロジェクト番号	Video Stitcher API を使用する Google Cloud プロジェクトのプロジェクト番号: PROJECT_NUMBER
OAuth トークン	Video Stitcher ユーザーロールを持つサービス アカウントの有効期間が短い OAuth トークン: OAUTH_TOKEN 有効期間が短い OAuth トークンの作成の詳細を確認します。 重要なポイント: OAuth トークンは、有効期限が切れていない限り、複数のリクエストで再利用できます。
ネットワーク コード	広告をリクエストするためのアド マネージャー ネットワーク コード: NETWORK_CODE
VOD 構成 ID	Vod ストリーム イベントの作成時に指定した VOD 構成 ID: VOD_CONFIG_ID

アド マネージャーにストリーム登録リクエストを送信する

ストリーム登録エンドポイントに POST リクエストを行います。返される JSON レスポンスには、マニフェスト操作サーバーと関連する Pod Serving API エンドポイントに送信するストリーム ID が含まれます。

API エンドポイント

POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json

パスパラメータ

NETWORK_CODE

お客様の Google アド マネージャー ネットワークのコード

JSON エンコードされた本文パラメータ

targeting_parameters

オプションの JSON エンコードのターゲティング パラメータのセット。

レスポンス JSON

media_verification_url	再生トラッキング イベントの ping のベース URL。このベース URL に広告イベント ID が追加され、完全なメディア確認 URL が生成されます。 MEDIA_VERIFICATION_URL
metadata_url	連続配信広告のメタデータをリクエストする URL。 METADATA_URL
stream_id	現在のストリーム セッションの識別に使用される文字列。 STREAM_ID
valid_for	現在のストリーム セッションが期限切れになるまでの残り時間。dhms（日、時間、分、秒）形式で指定します。たとえば、2h0m0.000s は 2 時間の期間を表します。
valid_until	現在のストリーム セッションが期限切れになる時刻。yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm 形式の ISO 8601 の日時文字列で指定します。

リクエストの例（cURL）

curl -X POST \
     -H "Content-Type: application/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

レスポンスの例

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

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

JSON レスポンスを解析し、関連する値を保存します。

ヒント: API レスポンスで返される URL は、予告なく変更される場合があります。そのため、URL を自分で作成するのではなく、API レスポンスで指定されたとおりの URL を使用します。これにより、URL が変更された場合でも、コードが引き続き正しく機能します。

Cloud Video Stitcher VOD セッションを生成する

VOD セッション登録エンドポイントに POST リクエストを送信します。レスポンスとして、ストリーム マニフェスト URI と、ミッドロール挿入点、広告、広告イベントに関するメタデータを含む JSON レスポンスが返されます。

API エンドポイント

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

パスパラメータ

PROJECT_NUMBER	Google Cloud プロジェクト番号。
LOCATION	Google Cloud リージョン。
NETWORK CODE	お客様の Google アド マネージャー 360 ネットワークのコード

JSON エンコードされた本文パラメータ

vodConfig	プロジェクト番号、ロケーション、VOD 構成 ID を含む文字列。形式は次のとおりです。 projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking	クライアント側トラッキングを有効にするには、"CLIENT" に設定します。
gamSettings	次の形式のネットワーク コードとストリーム ID を含むオブジェクト。 { "networkCode":"NETWORK_CODE", "streamId":"STREAM_ID" }

レスポンス JSON

name	セッション ID を含む VOD セッションの名前。
playUri	動画プレーヤーに読み込んで再生する、ステッチされたストリーム マニフェストの URI。 SESSION_PLAYBACK_URI
adTracking	リクエスト本文で API に送信された同じ adTracking 値。
vodConfig	リクエスト本文で API に送信されたものと同じ vodConfig 文字列。
gamSettings	リクエスト本文で API に送信された gamSettings オブジェクトと同じオブジェクト。

リクエストの例（cURL）

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

レスポンスの例

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

レスポンスの受信後、レスポンス オブジェクトの playUri フィールドの URI を参照して、広告合成されたライブ ストリームを再生できます。

アド マネージャーから連続配信広告のメタデータをリクエストする

アド マネージャーでストリームを登録したときに受け取った metadata_url に対して GET リクエストを行います。この手順は、再生 URI からステッチされたマニフェストを受け取った後に行う必要があります。

ストリームのミッドロール挿入点、広告、広告イベントを記述する JSON オブジェクトを受け取ります。

API エンドポイント

GET: METADATA_URL
Host: dai.google.com

レスポンス JSON

tags	ストリーム内で発生する広告メディア イベントを記述する Key-Value ペアのセット。各キーは、ストリームの ID3 メタデータに表示される広告メディア ID の最初の 17 文字か、「progress」イベントの場合は広告メディア ID 全体で構成されます。各値は、次のプロパティを持つオブジェクトです。 ad: 広告メディア イベントを含む広告の ID。 ad_break_id: 広告メディア イベントを含むミッドロール挿入点の ID。 type: 広告メディア イベントのタイプ。値は次のいずれかです。 start - 広告が開始された firstquartile - 広告は 25% 完成しました。 midpoint - 広告は 50% 完了しています。 thirdquartile - 広告の作成が 75% 完了しています。 complete - 広告は終了しました。 progress - 広告の再生中に 1 秒ごとに起動されます。
ads	ストリーム内に表示される広告を記述する Key-Value ペアのセット。各キーは広告 ID です。各値は、次のプロパティを持つオブジェクトです。 ad_break_id: 広告メディア イベントを含むミッドロール挿入点の ID。 position: 広告ブレーク内の広告の位置。ブレークの最初の広告は 1 の位置にあることに注意してください。 duration: 広告の再生時間（浮動小数点数）。 title: VAST で定義されている広告のタイトル。 description: VAST で定義されている広告の説明。 ad_system: VAST で定義されている広告システム。 ad_system: VAST で定義されている広告 ID。 ad_system: VAST で定義されているクリエイティブ ID。 clickthrough_url: ユーザーが広告を操作したときに開く URL。 universal_ad_id: VAST で定義されているユニバーサル広告 ID を表すオブジェクト。
ad_breaks	ストリーム内で発生するミッドロール挿入点を表す Key-Value ペアのセット。各キーはミッドロール挿入点 ID です。各値は、次のプロパティを持つオブジェクトです。 type: 広告ブレークのタイプ。値は次のいずれかになります。 pre: プレロール広告を表します。 mid: ミッドロール広告を表します。 post: ポストロール広告を表します。 duration: 広告ブレークの再生時間（浮動小数点数）です。 expected_duration: 予想される広告ブレークの再生時間（浮動小数点数）です。 ads: ミッドロール挿入点内の広告の数。

リクエストの例（cURL）

curl METADATA_URL

JSON レスポンスの例

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

これらの値を保存して、動画ストリーム内のタイミング設定されたメタデータ イベントに関連付けます。

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

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

1. メディア イベントをキューに保存し、各メディア ID とタイムスタンプ（プレーヤーによって表示された場合はタイムスタンプ）を保存します。
2. プレーヤーからの更新ごとに、または設定した頻度（500 ms が推奨）で、イベントのタイムスタンプを再生ヘッドと比較して、最近再生されたイベントがメディア イベントのキューにあるかどうかを確認します。
3. 再生したメディア イベントの場合は、保存されているミッドロール挿入点タグでメディア ID を検索してタイプを確認します。ミッドロール挿入点タグ オブジェクトには、メディア ID の切り捨てバージョンのみが含まれます。このバージョンは、google_ 接頭辞の後の最初の 10 桁に限定されているため、ID3 メディア認証 ID とタグ オブジェクト内のキーは直接一致しません。これは、ID3 イベントが届く前にイベント確認ピンが送信されないようにするためです。広告イベントの完全なメディア検証 URL を生成するには、ストリーム作成レスポンスの media_verification_url 値に完全な広告イベント ID を追加します。
4. 「progress」イベントを使用して、ユーザーが広告ブレークの内側に入るかどうかを追跡します。HTTP エラーコードを回避するため、これらのイベントをメディア検証エンドポイントに送信しないでください。他のイベントタイプの場合は、メディア ID をメディア確認の URL に追加し、GET リクエストを行って再生を追跡します。
5. キューからメディア イベントを削除します。

API エンドポイント

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

パスパラメータ

MEDIA_VERIFICATION_URL	ストリーム登録エンドポイントによって media_verification_url フィールドに返された値： MEDIA_VERIFICATION_URL
AD_MEDIA_ID	ストリームの ID3 メタデータに表示される完全な広告メディア ID： AD_MEDIA_ID

期待される戻り値

HTTP/1.1 204 No Content	成功した空のレスポンス。
HTTP/1.1 404 Not Found	メディア確認 ID を認識できませんでした。
HTTP/1.1 409 Conflict	メディア確認 ID はすでに送信されています。

リクエストの例（cURL）

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

レスポンスの例

HTTP/1.1 204 No Content

制限事項

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

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