Начать

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

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

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

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

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

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

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

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

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

Поскольку IMA SDK загружает зависимости по тому же протоколу, что и страница, с которой он загружается, для тестирования приложения необходимо использовать веб-сервер. Самый простой способ запустить локальный сервер разработки — использовать встроенный сервер Python.

  1. Используя командную строку, из каталога, содержащего файл index.html, запустите:
      python -m http.server 8000
  2. В веб-браузере перейдите по адресу http://localhost:8000/

Вы также можете использовать любой другой веб-сервер, например HTTP-сервер Apache .

2. Создайте простой видеоплеер

Сначала измените index.html , чтобы создать простой видеоэлемент HTML5, содержащийся в элементе-оболочке, и кнопку для запуска воспроизведения. Также добавьте необходимые теги для загрузки файлов style.css иads.js. Затем измените style.css , чтобы видеоплеер реагировал на мобильные устройства. Наконец, вads.js запускает воспроизведение видео при нажатии кнопки воспроизведения.

index.html

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>
стиль.css
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
реклама.js
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

После выполнения этого шага, когда вы открываете index.html в своем браузере (через сервер разработки), вы сможете увидеть элемент видео, и видео должно запускаться при нажатии кнопки воспроизведения.

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

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

index.html
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Прикрепите обработчики страниц и видеоплееров.

Чтобы изменить поведение видеоплеера с помощью JavaScript, добавьте обработчики событий, которые запускают следующие действия:

  • Когда страница загрузится, инициализируйте IMA SDK.
  • При нажатии кнопки воспроизведения видео загрузите рекламу (если реклама еще не загружена).
  • При изменении размера окна браузера обновите размеры элемента video и adsManager , чтобы страница адаптировалась к мобильным устройствам.
реклама.js
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

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

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

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

index.html
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
стиль.css
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
реклама.js
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. Инициализируйте AdsLoader и сделайте запрос рекламы.

Чтобы запросить набор объявлений, создайте экземпляр ima.AdsLoader . Этот экземпляр принимает объект AdDisplayContainer в качестве входных данных и может использоваться для обработки объектов ima.AdsRequest , связанных с указанным URL-адресом тега объявления. Рекламный тег, используемый в этом примере, содержит 10-секундную рекламу в начале ролика. Вы можете проверить этот или любой другой URL-адрес рекламного тега с помощью IMA Video Suite Inspector .

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

реклама.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var 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 = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. Слушайте события AdsLoader

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

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

реклама.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. Запустите AdsManager.

Чтобы начать воспроизведение рекламы, вам необходимо запустить AdsManager . Для полной поддержки мобильных браузеров это должно запускаться при взаимодействии с пользователем.

реклама.js
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. Сделайте AdsManager отзывчивым

Чтобы убедиться, что размер рекламы динамически изменяется в соответствии с размером видеоплеера, если экран меняет размер или ориентацию, событие изменения размера окна должно вызыватьadsManager.resize adsManager.resize() .

реклама.js
...

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

...

10. Слушайте события AdsManager

AdsManager также генерирует несколько событий, которые необходимо обработать. Эти события используются для отслеживания изменений состояния, запуска воспроизведения и приостановки видеоконтента, а также регистрации ошибок.

Обработка ошибок

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

реклама.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

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

Когда AdsManager готов вставить рекламу для показа, он запускает событие CONTENT_PAUSE_REQUESTED . Обработайте это событие, вызвав паузу в базовом видеопроигрывателе. Аналогично, когда объявление завершается, AdsManager запускает событие CONTENT_RESUME_REQUESTED . Обработайте это событие, перезапустив воспроизведение основного видеоконтента.

реклама.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

Запуск функции «нажми на паузу» на мобильных устройствах

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

Чтобы реализовать функцию «нажми на паузу», добавьте в AdContainer обработчик кликов и запускайте события воспроизведения или паузы в базовом видео.

реклама.js
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Запуск воспроизведения нелинейной рекламы

AdsManager приостанавливает видеоконтент, когда реклама готова к воспроизведению, но такое поведение не учитывает нелинейные объявления, где контент должен продолжать воспроизводиться во время отображения рекламы. Для поддержки нелинейной рекламы слушайте, как AdsManager генерирует событие LOADED . Затем проверьте, является ли объявление линейным, и если нет, возобновите воспроизведение видеоэлемента.

реклама.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

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