開始使用 IMA DAI SDK

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

選取感興趣的動態廣告解決方案

全方位服務 DAI

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

IMA DAI 總覽

實作 IMA DAI SDK 涉及兩個主要元件，如本指南所示：

  • StreamRequest： VODStreamRequest 或 LiveStreamRequest：定義串流要求的物件。串流要求可以是隨選影片或直播串流。要求會指定內容 ID，以及 API 金鑰或驗證權杖和其他參數。
  • 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 伺服器。

建立簡單的影片播放器

首先，請修改 dai.html，建立簡單的 HTML5 影片元素和 div，用於點閱。另外，請新增必要的標記，以便載入 dai.css 和 dai.js 檔案，以及匯入 hls.js 影片播放器。接著修改 dai.css，指定網頁元素的大小和位置。最後，請在 dai.js 中定義變數，用於儲存串流要求資訊，以及在網頁載入時執行的 initPlayer() 函式。

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 DAI 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'

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

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

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

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

載入 IMA DAI SDK

接著，請在 dai.html 中使用指令碼標記新增 IMA 架構，並放在 dai.js 的標記前面。

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 並提出串流要求

如要要求一組廣告，請建立 ima.dai.api.StreamManager，負責要求及管理 DAI 串流。建構函式會採用影片元素，而產生的例項會採用廣告 UI 元素來處理廣告點擊。

接著，定義要求串流的函式。這個範例包含 VOD 和直播的函式，分別建立 VODStreamRequest 和 LiveStreamRequest 的例項，然後使用 streamRequest 參數呼叫 streamManager.requestStream()。對於直播，您還需要新增處理程序，以便監聽計時中繼資料事件，並將事件轉送至 StreamManager。您可以根據用途將程式碼加上或取消註解。這兩種方法都會使用選用的 API 金鑰。如果您使用的是受保護的串流，則需要建立動態廣告插播驗證金鑰。

此範例中的兩個串流都未受保護，因此不會使用 apiKey。

dai.js

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

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(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(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

處理串流事件

最後，您需要為主要影片事件實作事件監聽器。這個簡單的範例會呼叫 onStreamEvent() 函式，處理 LOADED、ERROR、AD_BREAK_STARTED 和 AD_BREAK_ENDED 事件。這個函式會處理串流載入和錯誤，並在 SDK 要求的情況下，在播放廣告時停用播放器控制項。載入串流時，影片播放器會使用 loadUrl() 函式載入並播放提供的網址。

您可能還想為影片元素的 pause 和 start 事件設定事件監聽器，以便在 IMA 在廣告插播期間暫停時，讓使用者繼續播放。

如要使用 DAI，自訂播放器必須將直播的 ID3 事件傳遞至 IMA DAI SDK，如範例程式碼所示。

dai.js

var isAdBreak;

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

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     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.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');
      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 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();
  });
}

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 請求及顯示廣告。如要進一步瞭解進階 SDK 功能，請參閱其他指南或 GitHub 上的範例。