Клиентское видеоплеер для потоков VOD

API обслуживания модулей Google DAI позволяет выполнять вставку рекламы на стороне сервера с помощью Google Ads, сохраняя при этом контроль над собственным сшиванием видео.

В этом руководстве показано, как взаимодействовать с API обслуживания модулей и достигать аналогичной функциональности с помощью IMA DAI SDK. По конкретным вопросам о поддерживаемых функциях обращайтесь к своему менеджеру аккаунта Google.

API обслуживания модулей поддерживает потоки обслуживания модулей в протоколах потоковой передачи HLS или MPEG-DASH. В этом руководстве основное внимание уделяется потокам HLS и на конкретных этапах освещаются ключевые различия между HLS и MPEG-DASH.

Чтобы интегрировать API обслуживания Pod в ваше приложение для потоков VOD, выполните следующие шаги:

Отправьте запрос на регистрацию трансляции в Менеджер рекламы.

Отправьте POST-запрос к конечной точке регистрации потока. Вы, в свою очередь, получаете ответ JSON, содержащий идентификатор потока для отправки на ваш сервер манифестов и связанные с ним конечные точки API обслуживания модулей.

конечная точка API 

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Параметры пути

{network_code} Код вашей сети Google Ad Manager 360.

Параметры тела JSON

targeting_parameters Объект JSON, содержащий параметры таргетинга рекламы. Необходимый

Ответ в формате JSON

media_verification_url Базовый URL-адрес для проверки связи с событиями отслеживания воспроизведения. Полный URL-адрес проверки мультимедиа формируется путем добавления идентификатора рекламного события к этому базовому URL-адресу.
metadata_url URL-адрес для запроса метаданных рекламного модуля .
stream_id Строка, используемая для идентификации текущего сеанса потока.
valid_for Количество времени, оставшееся до истечения текущего сеанса потоковой передачи, в формате dhms (дни, часы, минуты, секунды). Например, 2h0m0.000s соответствует продолжительности 2 часа.
valid_until Время истечения текущего сеанса потоковой передачи в виде строки даты и времени ISO 8601 в формате yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .

Пример запроса (cURL) 

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

Пример ответа 

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

В случае ошибок возвращаются стандартные коды ошибок HTTP без тела ответа JSON.

Проанализируйте ответ JSON и сохраните соответствующие значения.

Запросите манифест потока у манипулятора манифеста.

Каждый манипулятор манифеста имеет разные форматы запросов и ответов. Свяжитесь с поставщиком манипуляторов, чтобы узнать его конкретные требования. Если вы реализуете собственный манипулятор манифеста, прочтите руководство по манипулятору манифеста, чтобы понять требования к этому компоненту.

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

Пример запроса (cURL) 

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Пример ответа (HLS) 

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

Воспроизвести трансляцию

Загрузите манифест, полученный с сервера манипуляции манифестами, в видеоплеер и запустите воспроизведение.

Запросить метаданные рекламного блока у Менеджера рекламы

Сделайте запрос GET к metadata_url , который вы получили на первом шаге. Этот шаг необходимо выполнить после того, как вы получили сшитый манифест от манипулятора манифеста. Взамен вы получаете объект JSON, содержащий следующие параметры:

tags Набор пар ключ-значение, содержащий все рекламные события, которые появляются в потоке. Ключами являются либо первые 17 символов идентификатора рекламного события, которые появляются в синхронизированных метаданных потока, либо, в случае событий типа progress , полный идентификатор рекламного события.

Каждое значение представляет собой объект, содержащий следующие параметры:

ad Идентификатор объявления, соответствующий ключу в объекте ads .
ad_break_id Идентификатор рекламной паузы, соответствующий ключу в объекте ad_breaks .
type Тип рекламного события. Типы рекламных событий:
start Уволено в начале объявления.
firstquartile Уволен в конце первого квартиля.
midpoint Снято в середине объявления.
thirdquartile Уволен в конце третьего квартиля.
complete Уволено в конце объявления.
progress Периодически активируется на протяжении всего объявления, чтобы уведомить приложение о воспроизведении рекламной паузы.
ads Набор пар ключ-значение, описывающий все объявления, которые появляются в потоке. Ключи — это идентификаторы объявлений, соответствующие значениям, найденным в объекте tags указанном выше. Каждое значение представляет собой объект, содержащий следующие параметры:
ad_break_id Идентификатор рекламной паузы, соответствующий ключу в объекте ad_breaks .
position Позиция, на которой это объявление появляется в наборе объявлений в рекламной паузе, в секундах с плавающей запятой.
duration Длина объявления в секундах с плавающей запятой.
clickthrough_url URL-адрес, который должен открываться при взаимодействии пользователя с этим объявлением, если он поддерживается.
ad_breaks Набор пар ключ-значение, описывающий все рекламные паузы, которые появляются в потоке. Ключами являются идентификаторы рекламных пауз, которые соответствуют значениям, найденным в tags и объектах ads перечисленных выше. Каждое значение представляет собой объект, содержащий следующие параметры:
type Тип рекламной паузы. Типы рекламных пауз: pre (преролл), mid (середина ролика) и post (после ролика).
duration Длина рекламной паузы в секундах с плавающей запятой.
ads Количество рекламы в этой рекламной паузе.

Сохраните эти значения, чтобы связать их с синхронизированными событиями метаданных в вашем видеопотоке.

Пример запроса (cURL) 

curl https://dai.google.com/.../metadata

Пример ответа 

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Слушайте рекламные события

Прослушивайте синхронизированные метаданные через триггерные рекламные события в аудио-/видеопотоке вашего видеоплеера.

Для потоков MPEG-TS метаданные отображаются в виде внутриполосных тегов ID3 ​​v2.3. Каждый тег метаданных имеет идентификатор TXXX , а значение начинается со строки google_ за которой следует ряд символов. Это значение — идентификатор рекламного события .

XXX в TXXX не является заполнителем. Строка TXXX — это идентификатор тега ID3, зарезервированный для «текста, определяемого пользователем».

Пример тега ID3 

TXXXgoogle_1234567890123456789

Для потоков MP4 они отправляются как внутриполосные события emsg, которые эмулируют теги ID3 v2.3. Каждое соответствующее поле emsg имеет значение scheme_id_uri либо https://aomedia.org/emsg/ID3 , либо https://developer.apple.com/streaming/emsg-id3 а также значение message_data начинающееся с ID3TXXXgoogle_ . Это значение message_data без префикса ID3TXXX является идентификатором рекламного события .

Пример окна emsg

Структура данных может различаться в зависимости от вашей библиотеки медиаплеера.

Если идентификатор рекламного события — google_1234567890123456789 ответ будет выглядеть следующим образом:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

Некоторые библиотеки медиаплееров автоматически представляют события emsg, которые имитируют теги ID3, как собственные теги ID3. В этом случае потоки MP4 представляют те же теги ID3, что и MPEG_TS.

Обновите пользовательский интерфейс клиентского приложения видеоплеера.

Каждый идентификатор рекламного события можно сопоставить с ключом в объекте tags из шага 4. Сопоставление этих значений выполняется в два этапа:

  1. Проверьте объект tags на наличие ключа, соответствующего полному идентификатору рекламного события. Если совпадение найдено, получите тип события и связанные с ним объекты ad и ad_break . Эти события должны иметь тип progress .

    Если совпадение для полного идентификатора рекламного события не найдено, проверьте объект tags на наличие ключа, совпадающего с первыми 17 символами идентификатора рекламного события. Получите тип события и связанные объекты ad и ad_break . Это должно получить все события с типами, отличными от progress .

  2. Используйте полученную информацию для обновления пользовательского интерфейса вашего плеера. Например, когда вы получаете событие start или первого progress , скройте элементы управления поиском вашего проигрывателя и отобразите наложение, описывающее текущую позицию объявления в рекламной паузе, например: «Объявление 1 из 3».

Примеры идентификаторов рекламных событий 

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Пример объекта тегов 

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

Отправка сигналов проверки носителя

Пинг-проверка мультимедиа должна отправляться в Менеджер рекламы каждый раз при получении рекламного события с типом, отличным от progress .

Чтобы создать полный URL-адрес проверки мультимедиа рекламного события, добавьте полный идентификатор рекламного события к значению media_verification_url из ответа на регистрацию потока.

Сделайте запрос GET с полным URL-адресом. Если запрос на проверку успешен, вы получите HTTP-ответ с кодом состояния 202 . В противном случае вы получите код ошибки HTTP 404 .

Пример запроса (cURL) 

curl https://{...}/media/google_5555555555123456789

Пример успешного ответа 

HTTP/1.1 202 Accepted

Дополнительные ресурсы