В этом руководстве рассказывается, как разработать клиентское приложение для загрузки прямой трансляции HLS или DASH с помощью Pod Serving API и вашего инструмента управления манифестом.
Требования
Прежде чем продолжить, необходимо:
Специальный ключ объекта для события прямой трансляции, настроенного с типом динамической вставки объявлений
Pod serving redirect. Чтобы получить этот ключ, выполните следующие действия:Настройте прямую трансляцию с динамической вставкой объявлений.
Используйте клиентскую библиотеку SOAP API, чтобы вызвать метод
LiveStreamEventService.createLiveStreamEventsс объектомLiveStreamEventи свойствомdynamicAdInsertionType, для которого задано значение перечисленияPOD_SERVING_REDIRECT. Все клиентские библиотеки перечислены в статье Клиентские библиотеки и примеры кода.
Определите, доступен ли SDK для интерактивной медиарекламы (IMA) для вашей платформы. Чтобы увеличить доход, рекомендуем использовать IMA SDK. Подробнее о том, как настроить IMA SDK для динамической вставки объявлений…
Как отправить запрос на создание потока
Когда пользователь выбирает поток, выполните следующие действия:
Отправьте запрос
POSTк методу сервиса трансляций. Подробную информацию можно найти в разделе Метод: stream.Передавайте параметры таргетинга объявлений в форматах
application/x-www-form-urlencodedилиapplication/json. Этот запрос регистрирует сеанс трансляции в Google DAI.В примере ниже показан запрос на трансляцию.
Кодировка формы
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const params = new URLSearchParams({ cust_params: 'section=sports&page=golf,tennis' }).toString(); const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: params }); console.log(await response.json());Кодировка JSON
const url = `https://dai.google.com/ssai/pods/api/v1/` + `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`; const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ cust_params: { section: 'sports', page: 'golf,tennis' } }) }); console.log(await response.json());Если все пройдет успешно, вы увидите примерно следующее:
{ "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS", "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/", "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata", "session_update_url": "https://dai.google.com/linear/.../session", "polling_frequency": 10 }В ответе JSON найдите идентификатор сеанса трансляции и сохраните другие данные для последующих шагов.
Метаданные объявлений с опросами
Чтобы запросить метаданные объявления, выполните следующие действия:
Прочитайте значение
metadata_urlиз ответа на запрос регистрации потока.Отправьте начальный запрос
GETконечной точкеmetadata_url.- Пропустите параметр запроса
delta_token. Это позволяет серверу возвращать полные метаданные для интервала DVR трансляции. Интервал DVR – это период времени, в течение которого зритель может перематывать и воспроизводить трансляцию. Ответ содержит полеnext_delta_token.
- Пропустите параметр запроса
Чтобы оптимизировать пропускную способность, сохраните значение
next_delta_tokenиз последнего ответа.В следующем запросе отправьте это значение в качестве параметра запроса
delta_token. Сервер возвращает только те метаданные, которые изменились с момента создания токена. Всегда отправляйте последний полученный токен. Не пытайтесь анализировать, изменять или создавать токен. Подробную информацию можно найти в статье Метод: метаданные.В примере ниже показано, как получить метаданные объявления.
// Initial request (returns full metadata and next_delta_token) let response = await fetch(metadata_url); let metadata = await response.json(); let deltaToken = metadata.next_delta_token; // Subsequent request (returns only changes since deltaToken) if (deltaToken) { const url = new URL(metadata_url); url.searchParams.append('delta_token', deltaToken); response = await fetch(url.toString()); const deltaMetadata = await response.json(); // Merge deltaMetadata into your local cache mergeMetadata(metadata, deltaMetadata); deltaToken = deltaMetadata.next_delta_token; }Если запрос выполнен успешно, вы получите ответ PodMetadata. Если вы укажете параметр
delta_token, ответ будет содержать только объявления, рекламные паузы и теги, которые сервер добавил или обновил с момента создания токена. Ответ также содержит новое значениеnext_delta_token. Если какие-либо рекламные паузы устарели, ответ также будет содержать списокobsolete_ad_break_idsрекламных пауз, которые нужно удалить из кеша.{ "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0", "obsolete_ad_break_ids": ["0003069407"], "tags":{ "google_1022389921":{ "ad":"0003069408_ad1", "ad_break_id":"0003069408", "type":"start" }, ... }, "ads":{ "0003069408_ad1":{ "ad_break_id":"0003069408", "position":1, "duration":10.01, "title":"External - Pod Midroll 1", "clickthrough_url":"https://.../", ... }, ... }, "ad_breaks":{ "0003069408":{ "type":"mid", "duration":30, "ads":3 }, ... } }Сохраните объект
tagsи объедините обновления в локальном кеше. Если параметрobsolete_ad_break_idsприсутствует, удалите эти рекламные паузы и связанные с ними объявления и теги из кеша.Установите таймер, используя значение
polling_frequency, чтобы регулярно запрашивать метаданные. В каждом опросе отправляйте значениеnext_delta_token, возвращенное в последнем ответе с метаданными, в качестве параметра запросаdelta_token.
Загрузите поток в видеопроигрыватель
Получив идентификатор сеанса из ответа на запрос регистрации, передайте его в инструмент управления манифестом или создайте URL манифеста, чтобы загрузить поток в видеопроигрыватель.
Инструкции по передаче идентификатора сеанса можно найти в документации к инструменту управления манифестом. Если вы разрабатываете инструмент управления манифестом, ознакомьтесь со статьей Инструмент управления манифестом для прямых трансляций.
Ниже приведен пример URL манифеста.
https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"
Когда проигрыватель будет готов, запустите воспроизведение.
Как отслеживать события объявлений
Проверьте формат контейнера трансляции для временных метаданных:
В потоках HLS с контейнерами Transport Stream (TS) для передачи временных метаданных используются временные теги ID3. Подробнее о формате CMAF с HLS…
В потоках DASH для указания событий в манифесте используются элементы
EventStream.В потоках DASH используются элементы
InbandEventStream, если сегменты содержат поля Event Message (emsg) для данных полезной нагрузки, включая теги ID3. Подробную информацию вы найдете в разделе InbandEventStream.В потоках CMAF, включая DASH и HLS, используются поля
emsg, содержащие теги ID3.
Чтобы извлечь теги ID3 из потока, следуйте инструкциям в руководстве по видеопроигрывателю. Подробную информацию вы найдете в руководстве по работе с временными метаданными.
Чтобы получить идентификатор события объявления из тегов ID3, выполните следующие действия:
- Отфильтруйте события по
scheme_id_uriс помощьюurn:google:dai:2018илиhttps://aomedia.org/emsg/ID3. Извлеките массив байтов из поля
message_data.В примере ниже данные
emsgдекодируются в JSON:{ "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3", "presentation_time": 27554, "timescale": 1000, "message_data": "ID3TXXXgoogle_1022389921", ... }Отфильтруйте теги ID3 в формате
TXXXgoogle_{ad_event_ID}:TXXXgoogle_1022389921
Показать данные о событиях объявлений
Чтобы найти объект TagSegment, выполните следующие действия:
Получите объект метаданных объявления
tagsиз метаданных объявления для опроса. Объектtags– это массив объектовTagSegment.Используйте полный идентификатор события объявления, чтобы найти объект
TagSegmentс типомprogress.Чтобы найти объект
TagSegmentдругого типа, используйте первые 17 символов идентификатора события объявления.Поскольку клиентское приложение периодически запрашивает метаданные объявлений, между моментом, когда видеопроигрыватель обнаруживает тег ID3 в потоке, и моментом, когда становятся доступны связанные с ним метаданные, может возникнуть задержка. Если клиентское приложение не находит тег ID3 среди сохраненных тегов, оставьте его в очереди и обработайте повторно после следующего опроса метаданных. Тег остается в очереди до завершения обработки.
Получив
TagSegment, используйте свойствоad_break_idв качестве ключа, чтобы найти объектAdBreakв объекте метаданных объявленияad_breaks.В следующем примере выполняется поиск объекта
AdBreak:{ "type":"mid", "duration":15, "ads":1 }Используйте данные
TagSegmentиAdBreak, чтобы показывать информацию о позиции объявления в рекламной паузе. Пример:Ad 1 of 3.
Отправка запросов для подтверждения событий
Для каждого события объявления, кроме типа progress, отправьте запрос для подтверждения события.
Динамическая вставка объявлений Google отбрасывает события progress, и их частая отправка может повлиять на производительность приложения.
Чтобы создать полный URL подтверждения медиаконтента для события объявления, выполните следующие действия:
Из ответа на запрос потока добавьте полный идентификатор события объявления к значению
media_verification_url.Выполните запрос
GETс полным URL:// media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/" const completeUrl = `${media_verification_url}google_1022389921`; const response = await fetch(completeUrl);Если запрос выполнен успешно, вы получите ответ с кодом статуса
202. В противном случае вы получите код ошибки404.
Монитор действий в потоке позволяет изучать журнал всех событий, связанных с объявлениями. Подробнее о том, как отслеживать трансляцию и устранять неполадки…