DAI 用 IMA SDK を設定する

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

関心のある DAI ソリューションを選択する

フルサービス DAI

このガイドでは、IMA DAI SDK を動画プレーヤー アプリに統合する方法について説明します。完成したサンプル統合を確認または実行する場合は、GitHub から簡単なサンプルをダウンロードしてください。

IMA DAI の概要

このガイドで説明するように、IMA DAI SDK の実装には主に次の 2 つのコンポーネントが関係します。

  • StreamRequest - VODStreamRequest または LiveStreamRequest: ストリーム リクエストを定義するオブジェクト。ストリーム リクエストは、ビデオ オンデマンドまたはライブ ストリームのいずれかになります。ライブ ストリームのリクエストではアセットキーが指定され、VOD のリクエストでは CMS ID と動画 ID が指定されます。どちらのリクエスト タイプにも、指定されたストリームへのアクセスに必要な API キーと、Google アド マネージャーの設定で指定された広告識別子を IMA SDK が処理するための Google アド マネージャー ネットワーク コードを任意で含めることができます。
  • StreamManager: ダイナミック広告挿入ストリームと DAI バックエンドとのやり取りを処理するオブジェクト。ストリーム マネージャーは、トラッキング ping を処理し、ストリーム イベントと広告イベントをパブリッシャーに転送します。

前提条件

  • 3 つの空のファイル
    • dai.html
    • dai.css
    • dai.js
  • Python がパソコン、またはテストに使用するウェブサーバーにインストールされている

開発用サーバーを起動する

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

  1. コマンドラインを使用して、index.html ファイルを含むディレクトリから次のコマンドを実行します。

    python -m http.server 8000

  2. ウェブブラウザで http://localhost:8000/ にアクセスします。

    Apache HTTP Server などの他のウェブサーバーも使用できます。

動画プレーヤーを作成する

まず、dai.html を変更して、HTML5 動画要素と、クリックスルーに使用する div を作成します。次の例では、IMA DAI SDK をインポートしています。詳しくは、IMA DAI SDK をインポートするをご覧ください。

また、dai.css ファイルと dai.js ファイルを読み込み、hls.js 動画プレーヤーをインポートするために必要なタグを追加します。次に、dai.css を変更して、ページ要素のサイズと位置を指定します。最後に、dai.js で、ストリーム リクエスト情報を保持する変数を定義し、ページ読み込み時に実行する initPlayer() 関数を定義して、クリック時にストリームをリクエストするように再生ボタンを設定します。

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

一時停止した広告ブレーク中に再生を再開するには、動画要素の pause イベントと start イベントのイベント リスナーを設定して、プレーヤーのコントロールを表示 / 非表示にします。

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

IMA DAI SDK を読み込む

次に、dai.html で、dai.js のタグの前にスクリプトタグを挿入して、IMA フレームワークを追加します。

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

StreamManager を初期化する

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

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

ストリーム リクエストを行う

ストリームをリクエストする関数を定義します。この例には、VOD とライブ配信の両方の関数が含まれています。これらの関数は、VODStreamRequest クラスと LiveStreamRequest クラスのインスタンスを作成します。streamRequest インスタンスを取得したら、ストリーム リクエスト インスタンスを使用して streamManager.requestStream() メソッドを呼び出します。

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

どちらのストリーミング リクエスト メソッドも、API キーを省略可能です。保護されたストリームを使用している場合は、DAI 認証キーを作成する必要があります。詳しくは、DAI 動画ストリーム リクエストを認証するをご覧ください。この例のストリームはどちらも DAI 認証キーで保護されていないため、apiKey は使用されていません。

ストリームのメタデータを解析する

また、タイムド メタデータ イベントをリッスンし、イベントを StreamManager クラスに転送して、IMA が広告ブレーク中に広告イベントを発行できるようにするハンドラも追加する必要があります。

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });
}
dai.js

このガイドでは、ストリーム再生に hls.js プレーヤーを使用していますが、メタデータの実装は使用するプレーヤーの種類によって異なります。

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

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

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}
dai.js

ストリームが読み込まれると、動画プレーヤーは loadUrl() 関数を使用して、指定された URL を読み込んで再生します。

これで、これで、IMA DAI SDK を使用して広告をリクエストし、表示できるようになりました。SDK のより高度な機能については、他のガイドまたは GitHub のサンプルをご覧ください。