このページは Cloud Translation API によって翻訳されました。

IMA DAI SDK スタートガイド

IMA SDK を使用すると、マルチメディア広告をウェブサイトやアプリに簡単に統合できます。IMA SDK では、 VAST 準拠の広告サーバーに広告をリクエストし、アプリでの広告再生を管理できます。IMA DAI SDK を使用すると、アプリは広告とコンテンツ動画（VOD またはライブコンテンツ）のストリームリクエストを行います。SDK は組み合わされた動画ストリームを返すため、アプリ内で広告とコンテンツ動画を切り替える必要はありません。

目的の DAI ソリューションを選択する

Pod サービング DAI

このガイドでは、IMA DAI SDK for HTML5 と、再生に hls.js を使用する動画プレーヤーを使用して、ライブまたは VOD コンテンツの DAI Pod Serving ストリームを再生する方法について説明します。HLS.js と Safari での再生の両方をサポートして完成したサンプル統合を表示または確認するには、HLS Pod 配信の例をご覧ください。DASH.js のサポートについては、DASH Pod の提供例をご覧ください。以下のサンプルアプリは HTML5 DAI GitHub リリースページからダウンロードできます。

DAI Pod Serving の概要

IMA DAI SDK を使用した連続配信広告の実装には、このガイドで説明する 2 つの主要コンポーネントが必要です。

PodStreamRequest / PodVodStreamRequest: Google の広告サーバーへのストリームリクエストを定義するオブジェクト。リクエストではネットワークコードを指定します。PodStreamRequest にはカスタムアセットキーと、オプションの API キーも必要です。どちらにも他の省略可能なパラメータが含まれます。
StreamManager: トラッキング ping の呼び出しやパブリッシャーへのストリームイベントの転送など、動画ストリームと IMA DAI SDK 間の通信を処理するオブジェクト。

前提条件

始める前に、次のものが必要になります。

空の 3 つのファイル:
- dai.html
- dai.css
- dai.js
テストに使用するコンピュータ、またはウェブサーバーやその他のホストされた開発環境にインストールされた Python

開発環境を構成する

SDK は読み込み元のページと同じプロトコルを使用して依存関係を読み込むため、ウェブサーバーを使用してアプリをテストする必要があります。ローカル開発用サーバーを起動する最も簡単な方法は、Python の組み込みサーバーを使用することです。

コマンドラインを使用して、index.html ファイルを含むディレクトリから次のコマンドを実行します。
```
python -m http.server 8000
```
注: http.server は Python 3.x でのみ使用できます。
ウェブブラウザで http://localhost:8000/ にアクセスします。

Apache HTTP Server など、他のホストされた開発環境やウェブサーバーを使用することもできます。

シンプルな動画プレーヤーを作成する

まず、dai.html を変更して、シンプルな HTML5 動画要素と、広告 UI 要素に使用する div を作成します。また、dai.css ファイルと dai.js ファイルの読み込み、hls.js 動画プレーヤーのインポートに必要なタグも追加します。

次に、dai.css を変更して、ページ要素のサイズと位置を指定します。最後に、dai.js で、ストリームリクエスト情報を保持する変数と、ページの読み込み時に実行する initPlayer() 関数を定義します。

ストリームリクエストの定数は次のとおりです。

BACKUP_STREAM: 広告プロセスで致命的なエラーが発生した場合に再生されるバックアップストリームの URL。
STREAM_URL: ライブ配信にのみ使用されます。Pod 配信を使用してマニフェストマニピュレータまたはサードパーティパートナーが提供する動画ストリーム URL。リクエストを行う前に、IMA DAI SDK によって提供されるストリーム ID を挿入する必要があります。この場合、ストリーム URL にプレースホルダ [[STREAMID]] が含まれています。このプレースホルダは、リクエストを行う前にストリーム ID に置き換えられます。
NETWORK_CODE: アドマネージャー 360 アカウントのネットワークコード。
CUSTOM_ASSET_KEY: ライブ配信にのみ使用されます。アドマネージャー 360 で連続配信広告を識別するカスタムアセットキー。これは、マニフェストマニピュレータまたはサードパーティの Pod 提供パートナーによって作成できます。
API_KEY: ライブ配信にのみ使用されます。IMA DAI SDK からストリーム ID を取得するために必須となる、オプションの API キー。

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA DAI SDK Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

IMA DAI SDK を読み込む

次に、dai.html のスクリプトタグ（dai.js のタグの前に）を使用して DAI フレームワークを追加します。

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
...

StreamManager を初期化してライブまたは VOD ストリームリクエストを行う

ライブ配信連続配信広告

一連の広告をリクエストするには、DAI ストリームのリクエストと管理を行う ima.dai.api.StreamManager を作成します。コンストラクタは動画要素を受け取り、結果として得られるインスタンスは広告 UI 要素を受け取り、広告インタラクションを処理します。

次に、Pod サービングライブストリームをリクエストする関数を定義します。この関数は、まず PodStreamRequest を作成し、ステップ 2 で提供された streamRequest パラメータを使用して構成し、そのリクエストオブジェクトを使用して streamManager.requestStream() を呼び出します。

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

VOD 連続配信広告の配信

次に、VOD ストリームを配信する連続配信広告をリクエストする関数を定義します。この関数は、まず PodVodStreamRequest を作成し、ステップ 2 で提供された streamRequest パラメータを使用して構成し、そのリクエストオブジェクトを使用して streamManager.requestStream() を呼び出します。

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

ストリームイベントを処理する

ライブ配信連続配信広告

次に、主要な動画イベントのイベントリスナーを実装します。この例では、onStreamEvent() 関数を呼び出して、STREAM_INITIALIZED、ERROR、AD_BREAK_STARTED、AD_BREAK_ENDED イベントを処理します。この関数は、ストリームの読み込みとエラーを処理します。また、広告の再生中にプレーヤーコントロールを無効にします。これは SDK で必要です。ストリームが読み込まれると、動画プレーヤーは loadStream() 関数を使用して、指定された URL を読み込み、再生します。

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

VOD 連続配信広告の配信

次に、主要な動画イベントのイベントリスナーを実装します。この例では、onStreamEvent() 関数を呼び出して、STREAM_INITIALIZED、LOADED、ERROR、AD_BREAK_STARTED、AD_BREAK_ENDED イベントを処理します。この関数は、ストリームの読み込みとエラーを処理します。また、広告の再生中にプレーヤーコントロールを無効にします。これは SDK で必要です。

また、VOD Pod 提供ストリームでは、STREAM_INITIALIZED イベントに応じて StreamManager.loadStreamMetadata() を呼び出す必要があります。また、動画技術パートナー（VTP）にストリーム URL をリクエストする必要もあります。loadStreamMetadata() の呼び出しが成功すると、LOADED イベントがトリガーされます。このイベントで、ストリーム URL を使用して loadStream() 関数を呼び出し、ストリームを読み込んで再生する必要があります。

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

ストリームメタデータを処理する

このステップでは、メタデータのイベントリスナーを実装して、広告イベントが発生したときに SDK に通知します。インストリームメタデータイベントのリッスンは、ストリーム形式（HLS または DASH）、ストリームタイプ（ライブまたは VOD ストリーム）、プレーヤータイプ、使用する DAI バックエンドのタイプによって異なります。詳しくは、時間指定メタデータガイドをご覧ください。

HLS ストリーム形式（ライブストリームと VOD ストリーム、HLS.js プレーヤー）

HLS.js プレーヤーを使用している場合は、HLS.js の FRAG_PARSING_METADATA イベントをリッスンして ID3 メタデータを取得し、StreamManager.processMetadata() を使用して SDK に渡します。

すべてが読み込まれて準備が整った後で動画を自動的に再生するには、HLS.js の MANIFEST_PARSED イベントをリッスンして再生をトリガーします。

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(event, data) {
  if (streamManager && data) {
    // For each ID3 tag in the metadata, pass in the type - ID3, the
    // tag data (a byte array), and the presentation timestamp (PTS).
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js（DASH ストリーム形式、ライブ、VOD ストリームタイプ）

DASH.js プレーヤーを使用している場合、ライブストリームまたは VOD ストリームの ID3 メタデータをリッスンするには、次のように異なる文字列を使用する必要があります。

ライブ配信: 'https://developer.apple.com/streaming/emsg-id3'
VOD ストリーム: 'urn:google:dai:2018'

StreamManager.processMetadata() を使用して、ID3 メタデータを SDK に渡します。

すべてが読み込まれて準備ができたら、動画コントロールを自動的に表示するには、DASH.js の MANIFEST_LOADED イベントをリッスンします。

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

ライブ配信を行う Shaka プレーヤー（DASH ストリーム形式）

ライブ配信の再生に Shaka プレーヤーを使用している場合は、文字列 'emsg' を使用してメタデータイベントをリッスンします。次に、StreamManager.onTimedMetadata() の呼び出しで、そのイベントメッセージデータを使用します。

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

VOD ストリーム（DASH ストリーム形式）を使用する Shaka プレーヤー

VOD ストリームの再生に Shaka プレーヤーを使用している場合は、文字列 'timelineregionenter' を使用してメタデータイベントをリッスンします。次に、StreamManager.processMetadata() の呼び出しで、このイベントメッセージデータを文字列 'urn:google:dai:2018' とともに使用します。

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

プレーヤーイベントを処理する

動画要素の pause イベントと start イベントにイベントリスナーを追加して、SDK がミッドロール挿入点で一時停止したときにユーザーが再生を再開できるようにします。

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

これで、これで、IMA DAI SDK for HTML5 を使用して、連続配信広告配信ストリームで広告をリクエストして表示できます。高度な SDK 機能については、他のガイドまたは GitHub のサンプルをご覧ください。

IMA DAI SDK スタートガイド

Pod サービング DAI

DAI Pod Serving の概要

前提条件

開発環境を構成する

シンプルな動画プレーヤーを作成する

dai.html

dai.css

dai.js

IMA DAI SDK を読み込む

dai.html

StreamManager を初期化してライブまたは VOD ストリーム リクエストを行う

ライブ配信連続配信広告

dai.js

VOD 連続配信広告の配信

dai.js

ストリーム イベントを処理する

ライブ配信連続配信広告

dai.js

VOD 連続配信広告の配信

ストリーム メタデータを処理する

HLS ストリーム形式（ライブ ストリームと VOD ストリーム、HLS.js プレーヤー）

DASH.js（DASH ストリーム形式、ライブ、VOD ストリーム タイプ）

ライブ配信を行う Shaka プレーヤー（DASH ストリーム形式）

VOD ストリーム（DASH ストリーム形式）を使用する Shaka プレーヤー

プレーヤー イベントを処理する

StreamManager を初期化してライブまたは VOD ストリームリクエストを行う

ストリームイベントを処理する

ストリームメタデータを処理する

HLS ストリーム形式（ライブストリームと VOD ストリーム、HLS.js プレーヤー）

DASH.js（DASH ストリーム形式、ライブ、VOD ストリームタイプ）

プレーヤーイベントを処理する