開始使用 IMA DAI SDK

使用 IMA SDK，您就能輕鬆地將多媒體廣告整合至網站和應用程式。IMA SDK 可以 向任何 符合 VAST 規定的廣告伺服器請求廣告，並管理應用程式中的廣告播放情形。透過 IMA DAI SDK，應用程式會針對 VOD 或直播內容，對廣告和內容影片發出串流請求。接著，SDK 會傳回合併的影片串流，這樣您無須管理應用程式內的廣告和內容影片切換作業。

選取感興趣的 DAI 解決方案

完整服務 DAI

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

IMA DAI 總覽

導入 IMA DAI 涉及兩項主要 SDK 元件，如本指南所示：

  • StreamRequest： VODStreamRequest 或 LiveStreamRequest：定義串流要求的物件。串流要求可以是隨選影片或直播。要求會指定內容 ID、API 金鑰或驗證權杖和其他參數。
  • StreamManager：這個物件會處理動態廣告插播串流，以及與 DAI 後端的互動。串流管理員也會處理追蹤連線偵測 (ping)，並將串流和廣告事件轉送至發布商。

必要條件

  • 三個空白檔案
    • dai.html
    • dai.css
    • dai.js
  • 在電腦上安裝 Python，或用來進行測試的網路伺服器

啟動開發伺服器

由於 IMA 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 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 SDK

接著，使用 dai.html 中的指令碼代碼在 dai.js 的代碼前面新增 IMA 架構。

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