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

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

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

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

• Настройка с использованием полного сервиса динамической вставки объявлений. Google Менеджер рекламы выбирает объявления и вставляет их непосредственно в поток контента.
• Настройка динамической вставки объявлений с показом пакетов. Google Менеджер рекламы предоставляет пакеты объявлений, которые можно вставлять в видеопроигрыватель или загружать в него.

Cloud stitching API Live Cloud stitching API VOD

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

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

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

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

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

Примечание. IMA DAI SDK для HTML5 поддерживает потоки HLS и DASH, но для их воспроизведения требуются разные медиапроигрыватели или расширения, например HLS.js или DASH.js, с разными реализациями.

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

Чтобы начать работу с потоками DASH с динамической вставкой объявлений и IMA, ознакомьтесь с примером приложения IMA DASH.js.

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

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

Создайте конфигурацию для прямой трансляции, используя собственный контент или тестовую трансляцию. В этом руководстве предполагается, что вы используете поток HLS.

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

Местоположение

Регион Google Cloud, в котором была создана конфигурация прямой трансляции: LOCATION

Номер проекта

Номер облачного проекта Google Cloud, в котором используется Video Stitcher API:PROJECT_NUMBER

Токен OAuth

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

OAUTH_TOKEN

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

Код сети

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

Идентификатор конфигурации трансляции

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

Ключ собственного объекта

Ключ специального объекта Менеджера рекламы, созданный в процессе настройки трансляции с помощью Video Stitcher API: CUSTOM_ASSET_KEY

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

Важно! Класс VideoStitcherLiveStreamRequest IMA DAI поддерживает как потоки HLS, так и потоки DASH с несколькими периодами. Рекламные паузы вставляются только между периодами DASH.

Примеры приложений IMA демонстрируют только запросы потоков HLS. При создании класса VideoStitcherLiveStreamRequest вы по-прежнему можете использовать потоки 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 и распакуйте простой пример HLS.js в новую папку. В этом примере показано веб-приложение, которое можно разместить локально для тестирования.

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

python3 -m http.server 8000

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

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

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

Запросить трансляцию

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

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

Пример:

// StreamManager which will be used to request ad-enabled 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() {
  requestVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...

function requestVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
  streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';
  streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';

  streamManager.requestStream(streamRequest);
}

Если файлы трансляции находятся в сегменте Cloud Storage, то для локального тестирования необходимо включить CORS для источника http://localhost:8000.

Перезагрузите страницу. После этого вы сможете запрашивать и воспроизводить трансляции.

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

Чтобы настроить запрос потока, добавьте параметры сеанса, которые переопределят конфигурацию Cloud Video Stitcher API по умолчанию. Для этого используйте VideoStitcherLiveStreamRequest.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);

Как вставить рекламную паузу

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

• Если вы используете собственную трансляцию, вам нужно вставить маркер объявления. Дополнительную информацию о поддерживаемых маркерах объявлений HLS и DASH можно найти в документации по маркерам объявлений.

• Если вы создали прямую трансляцию с помощью Google Cloud Livestream API, вставьте событие канала рекламной паузы.

Объявление воспроизводится сразу после вставки рекламной паузы.

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

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

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

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