Настройка 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 .