Настройка IMA SDK

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

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

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

Обзор клиентской части IMA

Реализация клиентской части IMA включает в себя четыре основных компонента SDK, которые описаны в этом руководстве:

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

Предварительные требования

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

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

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

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

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

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

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

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

Рекомендуется использовать только один экземпляр AdsLoader на протяжении всего жизненного цикла страницы. Для отправки дополнительных запросов рекламы создайте новый объект AdsRequest , но используйте тот же самый AdsLoader . Дополнительную информацию см. в разделе часто задаваемых вопросов (FAQ) по SDK IMA .

Отслеживайте и реагируйте на события загрузки рекламы и ошибки, используя 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);
}

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