开始使用

Stay organized with collections Save and categorize content based on your preferences.

借助 IMA SDK,您可以轻松地将多媒体广告集成到您的网站和应用中。IMA SDK 可以从任何符合 VAST 标准的广告服务器请求广告,并在您的应用中管理广告播放。借助 IMA DAI SDK,应用可以为广告和内容视频(VOD 或直播内容)发出视频流请求。然后,SDK 会返回一个组合的视频流,因此您无需管理应用中的广告和内容视频之间的切换。

本指南介绍了如何将 IMA SDK 集成到一个简单的视频播放器应用中。如果您想要查看或遵循已完成的示例集成,请从 GitHub 下载简单示例

IMA DAI 概览

实现 IMA DAI 涉及两个主要 SDK 组件,本指南对此进行了演示:

  • StreamRequest - VODStreamRequest LiveStreamRequest:用于定义流请求的对象。视频流请求可以用于视频点播或直播。请求会指定内容 ID,以及 API 密钥或身份验证令牌和其他参数。
  • StreamManager:处理动态广告插播流以及与 DAI 后端互动的对象。流管理器还会处理跟踪 ping,并将流和广告事件转发给发布商。

前提条件

在开始之前,您需要做好以下准备:

  • 三个空文件
    • dai.html
    • dai.css
    • 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.cssdai.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'

// 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,由其负责请求和管理 DAI 视频流。该构造函数采用视频元素,然后由生成的实例使用一个广告界面元素来处理广告点击。

然后,定义请求流的函数。此示例包含 VOD 和直播的函数,它们分别创建 VODStreamRequestLiveStreamRequest 的实例,然后使用 streamRequest 参数调用 streamManager.requestStream()。对于直播,您还需要添加一个处理程序来监听定时元数据事件并将事件转发到 StreamManager。您可以根据自己的用例注释或取消代码注释。这两种方法都会接受可选的 API 密钥。如果您使用的是加密流,则需要创建 DAI 身份验证密钥

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() 函数来处理 LOADEDERRORAD_BREAK_STARTEDAD_BREAK_ENDED 事件。此函数用于处理 SDK 所需的流加载和错误,以及在广告播放时停用播放器控件。视频流加载后,视频播放器会使用 loadUrl() 函数加载并播放提供的网址。

此外,您还需要为视频元素的 pausestart 事件设置事件监听器,以允许 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 上的示例