Как настроить динамическую вставку объявлений в режиме полного обслуживания

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

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

Обзор IMA DAI

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

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

Требования

  • Три пустых файла
    • 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 элемента видео, чтобы показывать и скрывать элементы управления проигрывателем.

/**
 * 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, который отвечает за запрос потоков с динамической вставкой объявлений и управление ими. Конструктор принимает элемент видео и элемент интерфейса объявления, чтобы обрабатывать клики по объявлениям.

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

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

Определите функции для запроса потоков. В этом примере есть функции для видео по запросу и прямых трансляций, которые создают экземпляры классов 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.