Как настроить IMA SDK для динамической вставки объявлений

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

IMA SDK позволяет легко интегрировать мультимедийные объявления на сайты и в приложения. IMA SDK может запрашивать объявления с любого совместимого с VAST сервера объявлений и управлять воспроизведением рекламы в ваших приложениях. С помощью IMA DAI SDK приложения отправляют запрос потока для видеообъявления и контента (видео по запросу или трансляции). Затем SDK возвращает комбинированный видеопоток, поэтому вам не нужно управлять переключением между рекламой и контентом в приложении.

Выберите решение для динамической вставки объявлений

Динамическая вставка объявлений с полной поддержкой

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

Общие сведения о динамической вставке объявлений с помощью IMA SDK

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

  • StreamRequest – объект VODStreamRequest или LiveStreamRequest, определяющий запрос потока. Запросы потока могут быть для видео по запросу или прямых трансляций. В запросах трансляций указывается ключ объекта, а в запросах видео по запросу – идентификатор CMS и идентификатор видео. В запросы обоих типов можно добавить ключ API, необходимый для доступа к определенным потокам, и код сети Google Менеджера рекламы, который позволит IMA SDK обрабатывать рекламные идентификаторы в соответствии с настройками Менеджера рекламы.
  • StreamManager: Объект, который обрабатывает потоки динамической вставки объявлений и взаимодействия с серверной частью DAI. Менеджер потока также обрабатывает пинги отслеживания и пересылает издателю события потока и объявлений.

Требования

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

Как запустить сервер разработки

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

  1. С помощью командной строки из каталога, содержащего файл index.html, выполните следующую команду:

    python -m http.server 8000

  2. В браузере перейдите на страницу http://localhost:8000/.

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

Как создать видеопроигрыватель

Сначала измените файл dai.html, чтобы создать видеоэлемент HTML5 и элемент div, который будет использоваться для перехода по клику. В приведенном ниже примере импортируется IMA DAI SDK. Подробнее о том, как импортировать IMA DAI SDK…

Также добавьте необходимые теги для загрузки файлов dai.css и dai.js, а также для импорта видеопроигрывателя hls.js. Затем измените параметр dai.css, чтобы задать размер и положение элементов страницы. Наконец, в dai.js определите переменные для хранения информации о запросе трансляции, функцию initPlayer(), которая будет выполняться при загрузке страницы, и настройте кнопку воспроизведения для запроса трансляции при нажатии.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}

Чтобы возобновить воспроизведение во время рекламной паузы, настройте прослушиватели событий для событий pause и start элемента video, чтобы показывать и скрывать элементы управления проигрывателем.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}

Как загрузить IMA DAI SDK

Затем добавьте фреймворк IMA с помощью тега script в dai.html перед тегом для dai.js.

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

Инициализация StreamManager

Чтобы запросить набор объявлений, создайте ima.dai.api.StreamManager, который будет отвечать за запрос и управление потоками DAI. Конструктор принимает видеоэлемент и элемент интерфейса объявления для обработки кликов по объявлению.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}

Как отправить запрос на создание потока

Определите функции для запроса потоков. В этом примере есть функции для VOD и трансляций, которые создают экземпляры класса VODStreamRequest и класса LiveStreamRequest. После создания экземпляра streamRequest вызовите метод streamManager.requestStream() с экземпляром запроса потока.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

Оба метода запроса потока принимают необязательный ключ API. Если вы используете защищенный поток, вам нужно создать ключ аутентификации для динамической вставки объявлений. Подробнее об аутентификации запросов потокового видео при динамической вставке объявлений… Ни один из потоков в этом примере не защищен ключом аутентификации для динамической вставки объявлений, поэтому параметр apiKey не используется.

Анализ метаданных потока

Вам также нужно добавить обработчик, который будет прослушивать события метаданных с временными метками и пересылать их в класс StreamManager, чтобы IMA мог запускать события объявлений во время рекламных пауз:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });
}

В этом руководстве для воспроизведения потока используется проигрыватель hls.js, но реализация метаданных зависит от типа используемого проигрывателя.

Как обрабатывать события потока

Реализуйте прослушиватели событий для основных событий видео. В этом примере события LOADED, ERROR, AD_BREAK_STARTED и AD_BREAK_ENDED обрабатываются путем вызова функции onStreamEvent(). Эта функция обрабатывает загрузку потока, ошибки потока и отключение элементов управления проигрывателем во время воспроизведения рекламы, что требуется IMA SDK.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}

Когда поток загружен, видеопроигрыватель загружает и воспроизводит указанный URL с помощью функции loadUrl().

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