API динамической вставки рекламы для прямых трансляций

API Google DAI позволяет реализовывать потоки с поддержкой Google DAI в средах, где реализация IMA SDK не поддерживается. Мы рекомендуем по-прежнему использовать IMA на платформах, где поддерживается IMA SDK.

Мы рекомендуем использовать DAI API на следующих платформах:

  • Смарт-телевизор Samsung (Тизен)
  • LG телевизор
  • HbbTV
  • Xbox (приложения JavaScript)
  • КайОС

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

Внедрите DAI API для прямых трансляций.

DAI API поддерживает линейные (LIVE) потоки с использованием протоколов HLS и DASH. Действия, описанные в этом руководстве, применимы к обоим протоколам.

Чтобы интегрировать API в ваше приложение для прямых трансляций, выполните следующие действия:

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

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

Пример тела запроса 

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

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

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

Ответ об ошибке

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

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

поток_ид
Это значение можно использовать для идентификации возвращаемого потока.
поток_манифест
Этот URL-адрес передается вашему медиаплееру для потокового воспроизведения.
media_verification_url
Этот URL-адрес является базовой конечной точкой для отслеживания событий воспроизведения.
метаданные_url
Этот URL-адрес используется для периодического опроса информации о предстоящих событиях потока.
session_update_url
Этот URL-адрес используется для обновления параметров запроса потока, отправленных во время первоначального запроса потока. Обратите внимание, что параметры этого запроса заменяют все параметры, установленные для предыдущего потока.
опрос_частота
Частота в секундах при запросе обновленных метаданных AdBreak от API DAI.

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

Установите таймер для опроса новых метаданных AdBreak с частотой опроса, используя URL-адрес метаданных. Если не указано в ответе потока, рекомендуемый интервал по умолчанию составляет 10 секунд.

Пример тела запроса 

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

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

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. Слушайте события ID3 и отслеживайте события воспроизведения.

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

  1. Сохраняйте медиа-события в очереди, сохраняя каждый идентификатор мультимедиа вместе с его меткой времени (если отображается проигрывателем).
  2. При каждом обновлении от проигрывателя или с заданной частотой (рекомендуется 500 мс) проверяйте очередь мультимедийных событий на наличие недавно воспроизведенных событий, сравнивая временные метки событий с указателем воспроизведения.
  3. Для медиа-событий, которые, как вы подтверждаете, воспроизводились, проверьте тип, найдя идентификатор мультимедиа в сохраненных тегах рекламной паузы. Имейте в виду, что сохраненные теги содержат только префикс идентификатора носителя, поэтому точное совпадение невозможно.
  4. Используйте события «прогресса», чтобы отслеживать, находится ли пользователь в рекламной паузе. Не отправляйте эти события в конечную точку проверки носителя. Для других типов событий добавьте идентификатор мультимедиа к конечной точке проверки мультимедиа и создайте запрос GET для отслеживания воспроизведения.
  5. Удалите медиа-событие из очереди.

Пример тела запроса 

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

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

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Вы можете проверить отслеживание событий в Stream Activity Monitor .

4. Обновите параметры сеанса прямой трансляции.

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

Пример тела запроса 

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

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

Successful response would be to look for - HTTP/1.1 200

Ограничения

При использовании API в веб-просмотрах в отношении таргетинга применяются следующие ограничения:

  • UserAgent: параметр пользовательского агента передается как значение, специфичное для браузера, а не базовой платформы.
  • rdid , idtype , is_lat : идентификатор устройства не передается должным образом, что ограничивает возможности следующих функций:
    • Ограничение частоты показов
    • Последовательная ротация объявлений
    • Сегментация аудитории и таргетинг

Лучшие практики

Помните, что конечная точка метаданных для индексов прямых трансляций основана на префиксе соответствующего тега ID3. Это сделано специально, чтобы предотвратить использование конечной точки метаданных для немедленной проверки связи со всеми узлами проверки.

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