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

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

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

{network_code} Код вашей сети Google Ad Manager 360.
{custom_asset} Пользовательский идентификатор, связанный с этим событием в Google AdManager.

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

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

Ответ в формате 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 \
     -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, содержащий следующие параметры:

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

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