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

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

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

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

Как воспроизводить видео по запросу, зарегистрированные с помощью Google Cloud Video Stitcher API

В этом руководстве рассказывается, как с помощью IMA DAI SDK для HTML5 запрашивать и воспроизводить сеанс трансляции видео по запросу в Google Cloud.

В этом руководстве расширен базовый пример из руководства по началу работы с IMA DAI.

Информацию об интеграции с другими платформами или об использовании клиентских IMA SDK можно найти в статье Interactive Media Ads SDK.

Чтобы посмотреть или повторить пример интеграции, скачайте пример Cloud Video Stitcher для HLS или DASH.

Как настроить проект Google Cloud

Настройте проект Google Cloud и сервисные аккаунты для доступа к нему.

Введите следующие переменные для использования в IMA SDK:

Местоположение
Регион Google Cloud, в котором была создана конфигурация видео по запросу: LOCATION
Номер проекта
Номер облачного проекта Google Cloud, в котором используется Video Stitcher API:PROJECT_NUMBER
Токен OAuth

Краткосрочный токен OAuth сервисного аккаунта с ролью пользователя Video Stitcher API: 

OAUTH_TOKEN

Подробнее о создании краткосрочных токенов OAuth… Токен OAuth можно использовать в нескольких запросах, пока не истечет срок его действия.

Код сети

Код сети Менеджера рекламы для запроса объявлений: NETWORK_CODE

Идентификатор конфигурации видео по запросу

Идентификатор конфигурации видео по запросу для трансляции видео по запросу: VOD_CONFIG_ID

Подробнее о том, как создать идентификатор конфигурации видео по запросу, рассказывается в руководстве по созданию конфигурации видео по запросу для вставки объявлений в облаке.

Настройте среду разработки

Примеры приложений IMA демонстрируют только запросы потоков HLS. При создании класса VideoStitcherVodStreamRequest вы по-прежнему можете использовать потоки DASH. При настройке проигрывателя, совместимого с DASH, необходимо настроить прослушиватель событий выполнения видеопроигрывателя, который может предоставлять метаданные видео в StreamManager.processMetadata(). Эта функция принимает три параметра:

  1. type – строка, которая должна иметь значение 'ID3' для потоков HLS и 'urn:google:dai:2018' для потоков DASH.

  2. data – строка данных сообщения для сообщений о событиях DASH.

  3. timestamp – число, обозначающее время начала сообщения о событии для потоков DASH.

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

Скачайте примеры IMA DAI для HTML5 и распакуйте ZIP-архив hls_js/simple в новую папку. В этом примере используется веб-приложение, которое можно разместить локально для тестирования.

Чтобы разместить пример локально, перейдите в новую папку и запустите следующую команду Python для запуска веб-сервера:

python3 -m http.server 8000

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

Откройте браузер и перейдите на страницу localhost:8000, чтобы увидеть видеопроигрыватель. Ваш браузер должен поддерживать библиотеку HLS.js.

Если все работает правильно, то при нажатии кнопки воспроизведения в видеопроигрывателе начнется показ короткометражного фильма Tears of Steel с рекламными паузами каждые 30 секунд.

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

Чтобы заменить пример трансляции на вашу трансляцию видео по запросу со вставленной рекламой, используйте класс VideoStitcherVodStreamRequest. Он позволяет автоматически создать рекламный сеанс с Google Менеджером рекламы. В интерфейсе Google Менеджера рекламы можно найти созданные сеансы динамической вставки объявлений, чтобы отслеживать их и устранять неполадки.

В существующем примере есть функции для запроса видео по запросу или прямой трансляции. Чтобы обеспечить совместимость с Google Cloud Video Stitcher API, необходимо добавить новую функцию, которая будет возвращать объект VideoStitcherVodStreamRequest.

Пример:

// StreamManager which will be used to request DAI streams.
let streamManager;
...

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(
    videoElement,
    adUiElement
  );
  streamManager.addEventListener(
    [
      google.ima.dai.api.StreamEvent.Type.LOADED,
      google.ima.dai.api.StreamEvent.Type.ERROR,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED
    ],
    onStreamEvent, false);

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

  videoElement.addEventListener('pause', () => {
    playButton.style.display = "block";
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVodVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...
function requestVodVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest();
  streamRequest.vodConfigId = 'VOD_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';

  streamManager.requestStream(streamRequest);
}

Перезагрузите страницу. Затем вы можете запросить и воспроизвести пользовательский поток видео по запросу.

Как добавить параметры трансляции (необязательно)

Чтобы настроить запрос потока, добавьте параметры сеанса, которые переопределят конфигурацию Cloud Video Stitcher API по умолчанию. Для этого используйте VideoStitcherVodStreamRequest.videoStitcherSessionOptions. Если вы укажете нераспознанный параметр, Cloud Video Stitcher API вернет ошибку HTTP 400. Подробнее об устранении неполадок…

Например, вы можете переопределить параметры манифеста с помощью приведенного ниже фрагмента кода, который запрашивает два манифеста потока с версиями, упорядоченными от самой низкой скорости передачи данных до самой высокой.

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

Организовать

Теперь, когда вы успешно разместили поток VOD с помощью Google Cloud Video Stitcher API и запросили его с помощью IMA DAI SDK для HTML5, важно очистить все ресурсы показа.

Следуйте инструкциям в руководстве Очистка VOD, чтобы удалить ненужные ресурсы и объекты.

В окне терминала, где вы запустили веб-сервер Python 3, введите команду ctrl+C, чтобы остановить локальный сервер.