Клиентское приложение-видеоплеер для прямых трансляций

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

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

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

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

Отправьте запрос на регистрацию потока в API обслуживания подов DAI.

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

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

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

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

Параметры тела, закодированные в форме

Необязательный набор параметров таргетинга, закодированных в форме.

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

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

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

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

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

В случае ошибок возвращаются стандартные коды ошибок 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

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

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

Опрос на предмет новых метаданных AdBreak

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

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

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

Пример запроса (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

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

• Справочная документация API
• Документация IMA SDK
• Сравнение типов реализации уровня DAI