開始使用 IMA DAI SDK

IMA SDK 可讓您輕鬆將多媒體廣告整合至您的網站和應用程式。IMA SDK 可向任何符合 VAST 規定的廣告伺服器要求廣告，並管理應用程式中的廣告播放作業。使用 IMA DAI SDK 時，應用程式可提供 廣告和內容影片的串流請求 (VOD 或直播內容)。接著，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 金鑰。如果您使用的是受保護的直播， 需要 建立 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);
}

處理串流事件

最後，您需要為主要影片事件實作事件監聽器。這個 簡單的範例會處理 LOADED、ERROR、AD_BREAK_STARTED 和 呼叫 onStreamEvent() 函式建立 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 上的範例。