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

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

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

Select the DAI solution you're interested in

Полный спектр услуг 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 : An object that handles dynamic ad insertion streams and interactions with the DAI backend. The stream manager also handles tracking pings and forwards stream and ad events to the publisher.

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

  • Три пустых файла
    • 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>


#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';
}

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

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

Parse stream metadata

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

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