開始使用

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

本指南說明如何將 IMA SDK 整合到簡單的影片播放器應用程式中。如果您想查看或遵循完成的範例整合，請從 GitHub 下載簡易範例。

IMA 動態廣告插播總覽

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

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

必要條件

開始操作前，您必須符合以下條件：

  • 三個空白檔案
    • dai.html
    • dai.cs
    • dai.js
  • 電腦中安裝的 Python 或網路伺服器，以便進行測試

1. 啟動開發伺服器

由於 IMA SDK 使用與載入頁面相同的通訊協定載入依附元件，因此您必須使用網路伺服器來測試應用程式。如要啟動本機開發伺服器，最簡單的方法是使用 Python 的內建伺服器。

  1. 使用指令列，從含有 index.html 檔案的目錄執行：

    python -m http.server 8000

  2. 使用網路瀏覽器前往 http://localhost:8000/

您也可以使用任何其他網路伺服器，例如 Apache HTTP Server。

2. 建立簡單的影片播放器

首先，修改 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.cs

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

// Live stream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2528370";
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');
}

3. 載入 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>

...

4. 初始化 StreamManager 並提出串流要求

如要請求一組廣告，請建立 ima.dai.api.StreamManager，負責請求及管理動態廣告插播串流。建構函式會採用影片元素，而產生的執行個體會採用廣告 UI 元素來處理廣告點擊。

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

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);
}

5. 處理串流事件

最後，您必須針對重大影片事件導入事件監聽器。這個簡易範例會呼叫 onStreamEvent() 函式，藉此處理 LOADED、ERROR、AD_BREAK_STARTED 和 AD_BREAK_ENDED 事件。這個函式會處理串流載入和錯誤，以及在廣告播放時停用播放器控制項，這是 SDK 要求的功能。串流載入時，影片播放器會使用 loadUrl() 函式載入並播放所提供的網址。

此外，您也必須為影片元素的 pause 和 start 事件設定事件監聽器，讓使用者在 IMA 作業期間暫停播放時繼續播放內容。

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 範例。