设置 IMA SDK

借助 IMA SDK，您可以轻松地将多媒体广告集成到网站和应用中。IMA SDK 可以从任何 符合 VAST 标准的广告服务器请求广告，并在您的应用中管理广告播放。借助 IMA 客户端 SDK，您可以继续控制内容视频播放，而 SDK 则负责处理广告播放。广告在位于应用内容视频播放器顶部的单独视频播放器中播放。

本指南演示了如何将 IMA SDK 集成到简单的视频播放器应用中。如果您想查看或跟随完成的示例集成，请从 GitHub 下载简单示例。如果您对预先集成 SDK 的 HTML5 播放器感兴趣，请查看 Video.js 的 IMA SDK 插件。

IMA 客户端概览

实现 IMA 客户端涉及四个主要 SDK 组件，本指南将对此进行演示：

  • AdDisplayContainer：一种容器对象，用于指定 IMA 呈现广告界面元素和衡量可见率（包括 Active View 和 Open Measurement）的位置。
  • AdsLoader： 一个用于请求广告并处理广告请求响应中的事件的对象。您只需实例化一个广告加载程序，该加载程序可在整个应用生命周期内重复使用。
  • AdsRequest： 用于定义广告请求的对象。广告请求会指定 VAST 广告代码的网址以及其他参数（例如广告尺寸）。
  • AdsManager： 一个包含广告请求响应、控制广告播放并监听 SDK 触发的广告事件的对象。

前提条件

在开始之前，您需要做好以下准备：

  • 三个空文件：
    • index.html
    • style.css
    • ads.js
  • 在用于测试的计算机或网络服务器上安装 Python

1. 启动开发服务器

由于 IMA SDK 加载依赖项时会使用协议，此协议与加载该 SDK 的网页所用的协议相同，因此您需要使用网络服务器来测试应用。要启动本地开发服务器，最简单的方法是使用 Python 的内置服务器。

  1. 在您的 index.html 文件所在的目录下使用命令行运行以下命令： 
      python -m http.server 8000
  2. 在网络浏览器中，前往 http://localhost:8000/

您也可以使用任何其他网络服务器，例如 Apache HTTP Server。

2. 创建简单的视频播放器

首先，修改 index.html，以创建一个简单的 HTML5 视频元素（包含在封装元素中），以及一个用于触发播放的按钮。以下示例导入了 IMA SDK 并设置了 AdDisplayContainer 容器元素。如需了解详情，请分别参阅 导入 IMA SDK 和 创建广告容器 步骤。 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

添加必要的标记以加载 style.css 和 ads.js 文件。然后，修改 styles.css，使视频播放器能够自适应移动设备。最后，在 ads.js 中，声明变量并在点击播放按钮时触发视频播放。

请注意，ads.js 代码段包含对 setUpIMA() 的调用，该调用在 初始化 AdsLoader 并发出广告请求 部分中定义。

3. 导入 IMA SDK

接下来，在 index.html 中插入一个脚本标记，将其放在 ads.js 对应的标记之前，以便添加 IMA 框架。 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. 创建广告容器

在大多数浏览器中，IMA SDK 使用专用的广告容器元素来展示广告和与广告相关的界面元素。此容器的大小必须能够从左上角覆盖视频元素。放置在此容器中的广告的高度和宽度由 adsManager 对象设置，因此您无需手动设置这些值。

如需实现此广告容器元素，请先在 video-container 元素内创建新的 div。然后，更新 CSS 以将元素定位在 video-element 的左上角。最后，添加 createAdDisplayContainer() 函数以使用新的广告容器 div 创建 AdDisplayContainer 对象。

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. 初始化 AdsLoader 并发出广告请求

如需请求广告，请创建 AdsLoader 实例。AdsLoader 构造函数以 AdDisplayContainer 对象作为输入，可用于处理与指定广告代码网址相关联的 AdsRequest 对象。此示例中使用的广告代码包含一个 10 秒的前贴片广告。您可以使用 IMA Video Suite Inspector 测试此广告代码网址或任何其他广告代码网址。

最佳实践是，在页面的整个生命周期内仅维护一个 AdsLoader 实例。如需发出其他广告请求，请创建一个新的 AdsRequest 对象，但重复使用相同的 AdsLoader。如需了解详情，请参阅 IMA SDK 常见问题解答。

使用 AdsLoader.addEventListener 监听并响应广告加载和错误事件。 监听以下事件：

  • ADS_MANAGER_LOADED
  • AD_ERROR

如需创建 onAdsManagerLoaded() 和 onAdError() 监听器，请参阅以下示例：

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
      'output=vast&unviewed_position_start=1&env=vp&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. 响应 AdsLoader 事件

当 AdsLoader 成功加载广告时，它会发出 ADS_MANAGER_LOADED 事件。解析传递给回调的事件，以初始化 AdsManager 对象。AdsManager 会加载广告代码网址的响应中定义的各个广告。

确保您能处理加载过程中发生的任何错误。如果广告未加载，请确保媒体播放继续进行，而不显示广告，以免干扰用户观看内容。 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

如需详细了解在 onAdsManagerLoaded() 函数中设置的监听器，请参阅以下子部分：

处理 AdsManager 错误

为 AdsLoader 创建的错误处理程序也可以用作 AdsManager 的错误处理程序。请参阅重用 onAdError() 函数的事件处理程序。 

adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
ads.js

处理播放和暂停事件

当 AdsManager 准备好插入广告以供展示时，它会触发 CONTENT_PAUSE_REQUESTED 事件。通过触发底层视频播放器的暂停来处理此事件。同样，当广告播放完毕时，AdsManager 会触发 CONTENT_RESUME_REQUESTED 事件。通过重新开始播放底层内容视频来处理此事件。

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

如需查看 onContentPauseRequested() 和 onContentResumeRequested() 函数的定义，请参阅以下示例： 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

处理非线性广告期间的内容播放

当广告准备好播放时，AdsManager 会暂停内容视频，但此行为不适用于非线性广告，因为在显示非线性广告时，内容会继续播放。 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

为了支持非线性广告，请监听 AdsManager 以发出 LOADED 事件。检查广告是否为线性广告，如果不是，则恢复视频元素的播放。

如需了解 onAdLoaded() 函数的定义，请参阅以下示例。 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. 在移动设备上触发点击即暂停功能

由于 AdContainer 叠加在视频元素上，用户无法直接与底层播放器互动。这可能会让移动设备上的用户感到困惑，因为他们希望能够通过点按视频播放器来暂停播放。为解决此问题，IMA SDK 会将广告叠加层中未由 IMA 处理的任何点击传递给 AdContainer 元素，以便在其中进行处理。这不适用于非移动浏览器上的线性广告，因为点击此类广告会打开点击后到达网址链接。

如需实现点击即暂停功能，请在窗口加载监听器中添加名为 adContainerClick() 的点击处理函数。

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. 启动 AdsManager

如需开始播放广告，请启动并开始 AdsManager。为了全面支持无法自动播放广告的移动浏览器，请通过用户与网页的互动（例如点击播放按钮）来触发广告播放。 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. 支持调整播放器大小

为了让广告能够动态调整大小并与视频播放器的大小相匹配，或者与屏幕方向的变化相匹配，请在响应窗口大小调整事件时调用 adsManager.resize()。 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

大功告成！您现在可以使用 IMA SDK 请求和展示广告了。如需了解更多高级 SDK 功能，请参阅其他指南或 GitHub 上的示例。