Настройка IMA SDK

Пакеты 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
    • стиль.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>

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

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

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

4. Создайте рекламный контейнер

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

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

<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 , связанных с указанным URL-адресом тега рекламы. Тег рекламы, используемый в этом примере, содержит 10-секундную рекламу в начале ролика. Вы можете протестировать этот или любой другой URL-адрес тега рекламы с помощью инструмента 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 загружает отдельные рекламные объявления, как определено в ответе на 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();
}
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

Для поддержки нелинейной рекламы дождитесь события 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();
  }
}
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 .