Настройка IMA SDK

IMA SDK облегчают интеграцию мультимедийной рекламы в ваши веб-сайты и приложения. IMA SDK могут запрашивать рекламу с любого совместимого с VAST сервера объявлений и управлять воспроизведением рекламы в ваших приложениях. С клиентскими SDK IMA вы сохраняете контроль над воспроизведением видеоконтента, в то время как 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.

Предпосылки

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

  • Три пустых файла:
    • индекс.html
    • стиль.css
    • объявления.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 video, содержащийся в элементе-обертке, и кнопку для запуска воспроизведения. Следующий пример импортирует IMA SDK и настраивает элемент-контейнер AdDisplayContainer . Для получения более подробной информации см. шаги Import the IMA SDK и Create the ad container соответственно. 

<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 . Для получения дополнительной информации см. FAQ по 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&impl=s&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

Для поддержки нелинейной рекламы ожидайте, пока 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 .