設定 DAI 專用的 IMA SDK

使用 IMA SDK，即可輕鬆將多媒體廣告整合至網站和應用程式。IMA SDK 可向任何 符合 VAST 規定的廣告伺服器請求廣告，並在應用程式中管理廣告播放。應用程式可透過 IMA DAI SDK，對廣告和內容影片 (隨選影片或直播內容) 提出串流請求。SDK 接著會傳回合併的影片串流，因此您不必在應用程式中管理廣告和內容影片之間的切換。

選取您感興趣的 DAI 解決方案

全方位服務 DAI

本指南說明如何將 IMA DAI SDK 整合至影片播放器應用程式。如要查看或跟著操作已完成的範例整合，請從 GitHub 下載簡單範例。

IMA DAI 總覽

如本指南所示，導入 IMA DAI SDK 包含兩個主要元件：

  • StreamRequest： VODStreamRequest 或 LiveStreamRequest：定義串流要求的物件。串流要求可以是隨選影片或直播串流。直播串流請求會指定素材資源金鑰，而 VOD 請求則會指定 CMS ID 和影片 ID。這兩種要求類型都可以選擇性地加入存取指定串流所需的 API 金鑰，以及 Google Ad Manager 聯播網代碼，供 IMA SDK 處理廣告 ID，如 Google Ad Manager 設定中所指定。
  • StreamManager： 這個物件會處理動態廣告插播串流，以及與 DAI 後端的互動。串流管理工具也會處理追蹤 Ping，並將串流和廣告事件轉送給發布商。

必要條件

  • 三個空白檔案
    • 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

如要要求一組廣告，請建立 ima.dai.api.StreamManager，負責要求及管理 DAI 串流。建構函式會採用影片元素和廣告 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 驗證金鑰保護，因此不會使用 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() 函式載入並播放提供的網址。

大功告成！您現在可以使用 IMA DAI SDK 請求及顯示廣告。如要瞭解更多進階 SDK 功能，請參閱其他指南或 GitHub 上的範例。