Как настроить IMA SDK

Выберите платформу: HTML5 Android iOS tvOS

IMA SDK позволяет легко интегрировать мультимедийные объявления на сайты и в приложения. IMA SDK может запрашивать объявления с любого совместимого с VAST сервера объявлений и управлять воспроизведением рекламы в ваших приложениях. При использовании клиентских IMA SDK вы управляете воспроизведением видеоконтента, а SDK отвечает за воспроизведение рекламы. Объявления показываются в отдельном видеопроигрывателе, расположенном поверх видеопроигрывателя контента приложения.

В этом руководстве рассказывается, как интегрировать IMA SDK в простое приложение с видеопроигрывателем. Если вы хотите посмотреть или повторить готовую интеграцию, скачайте простой пример с GitHub. Если вы хотите использовать проигрыватель HTML5 с уже интегрированным SDK, попробуйте плагин IMA SDK для Video.js.

Общие сведения о реализации IMA на стороне клиента

В клиентской IMA SDK есть четыре основных компонента, которые описаны в этом руководстве:

  • AdDisplayContainer – объект-контейнер, который указывает, где IMA отображает элементы интерфейса объявления и измеряет видимость, включая Active View и Open Measurement.
  • AdsLoader: объект, который запрашивает объявления и обрабатывает события из ответов на запросы объявлений. Вам нужно создать только один экземпляр загрузчика объявлений, который можно использовать в течение всего жизненного цикла приложения.
  • AdsRequest – объект, определяющий запрос объявлений. В запросах объявлений указывается URL тега объявления VAST, а также дополнительные параметры, например размеры объявления.
  • AdsManager: объект, который содержит ответ на запрос объявлений, управляет воспроизведением объявлений и отслеживает события объявлений, активируемые SDK.

Требования

Прежде чем начать, вам понадобится следующее:

  • Три пустых файла:
    • index.html
    • style.css
    • ads.js
  • Python, установленный на компьютере, или веб-сервер для тестирования.

1. Запустите сервер разработки

Поскольку IMA 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>

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

Добавьте необходимые теги, чтобы загрузить файлы style.css и ads.js. Затем измените файл styles.css, чтобы видеопроигрыватель был адаптивным для мобильных устройств. Наконец, в файле ads.js объявите переменные и настройте запуск видео при нажатии кнопки воспроизведения.

Обратите внимание, что фрагмент кода ads.js содержит вызов функции setUpIMA(), которая определена в разделе Инициализация AdsLoader и запрос объявлений .

3. Импортируйте IMA SDK

Затем добавьте фреймворк IMA с помощью тега script в файле index.html перед тегом для ads.js. 

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

4. Как создать контейнер для объявлений

В большинстве браузеров IMA SDK использует специальный контейнер для показа объявлений и связанных с ними элементов интерфейса. Этот контейнер должен быть такого размера, чтобы перекрывать элемент видео с левого верхнего угла. Высота и ширина объявлений, размещенных в этом контейнере, задаются объектом adsManager, поэтому вам не нужно указывать эти значения вручную.

Чтобы реализовать этот элемент контейнера объявлений, сначала создайте новый элемент div в элементе video-container. Затем обновите CSS, чтобы разместить элемент в левом верхнем углу video-element. Наконец, добавьте функцию createAdDisplayContainer() для создания объекта AdDisplayContainer с помощью нового контейнера объявлений div. 

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

5. Инициализируйте AdsLoader и отправьте запрос объявления

Чтобы запрашивать объявления, создайте экземпляр AdsLoader. Конструктор AdsLoader принимает объект AdDisplayContainer в качестве входных данных и может использоваться для обработки объектов AdsRequest, связанных с указанным URL тега объявления. Тег объявления, используемый в этом примере, содержит 10-секундную рекламу в начале видео. Вы можете проверить этот или любой другой URL тега объявления с помощью инструмента тестирования тегов VAST из IMA SDK.

Рекомендуем использовать только один экземпляр 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);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

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

6. Как реагировать на события AdsLoader

Когда тег AdsLoader успешно загружает объявления, он активирует событие ADS_MANAGER_LOADED. Проанализируйте событие, переданное в обратный вызов, чтобы инициализировать объект AdsManager. Тег AdsManager загружает отдельные объявления, определенные в ответе на URL тега объявления.

Обрабатывайте все ошибки, возникающие во время загрузки. Если объявления не загружаются, убедитесь, что воспроизведение медиаконтента продолжается без рекламы, чтобы не мешать пользователю смотреть контент. 

/**
 * 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();
}

Подробную информацию о слушателях, заданных в функции onAdsManagerLoaded(), можно найти в следующих подразделах:

Как устранять ошибки AdsManager

Обработчик ошибок, созданный для AdsLoader, также может использоваться в качестве обработчика ошибок для AdsManager. Посмотрите, как обработчик событий повторно использует функцию onAdError(). 

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

Как обрабатывать события воспроизведения и паузы

Когда 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);

Определения функций 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();
}

Как управлять воспроизведением контента во время показа параллельных объявлений

Тег AdsManager приостанавливает воспроизведение видеоконтента, когда объявление готово к показу, но это поведение не учитывает параллельные объявления, при показе которых контент продолжает воспроизводиться. 

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

Чтобы поддерживать параллельные объявления, настройте прослушивание события LOADED, которое генерирует AdsManager. Проверьте, является ли объявление линейным. Если нет, возобновите воспроизведение видео.

Определение функции 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();
  }
}

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

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

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

Готово! Теперь вы запрашиваете и показываете объявления с помощью IMA SDK. Чтобы узнать больше о расширенных функциях SDK, ознакомьтесь с другими руководствами или примерами на GitHub.