開始使用 IMA DAI SDK

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

選取所需的 DAI 解決方案

完整服務 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 Server。

建立簡易影片播放器

首先，修改 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 金鑰。如果您使用受保護的串流，則必須建立 DAI 驗證金鑰。

這個範例中的兩個串流均未受保護，因此並未使用 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 範例。