Настройка IMA SDK для DAI

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

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

Выберите интересующее вас решение DAI.

Полный спектр услуг DAI

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

Обзор IMA DAI

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

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

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

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

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

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

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

    python -m http.server 8000

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

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

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

Сначала измените файл dai.html , чтобы создать элемент HTML5-видео и div для отображения кликабельного элемента. В следующем примере импортируется SDK IMA DAI. Для получения более подробной информации см. раздел «Импорт SDK IMA DAI» .

Также добавьте необходимые теги для загрузки файлов 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>


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

#adUi {
  cursor: pointer;
}

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

dai.css
// 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';
  });
}
dai.js

Чтобы возобновить воспроизведение во время пауз в рекламе, настройте обработчики событий для событий 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';
}
dai.js

Загрузите SDK IMA DAI.

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

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

Инициализируйте 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);
}
dai.js

Отправить запрос на трансляцию

Определите функции для запроса потоков. В этом примере представлены функции как для видео по запросу (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);
}
dai.js

Оба метода запроса потока принимают необязательный ключ API. Если вы используете защищенный поток, вам необходимо создать ключ аутентификации DAI. Для получения более подробной информации см. раздел «Аутентификация запросов видеопотока DAI» . В этом примере ни один из потоков не защищен ключом аутентификации DAI, поэтому 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);
      });
    }
  });
}
dai.js

В этом руководстве для воспроизведения потока используется плеер 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();
  });
}
dai.js

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

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