API динамической вставки рекламы позволяет запрашивать и отслеживать потоки видео по запросу (VOD) DAI. Поддерживаются потоки HLS и DASH.
Сервис: dai.google.com.
Путь к методу stream
указан относительно https://dai.google.com
Метод: поток
Методы | |
---|---|
stream | POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream Создает поток HLS DAI для данного источника контента и идентификатора видео. Создает поток DASH DAI для данного источника контента и идентификатора видео. |
HTTP-запрос
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream
Заголовок запроса
Параметры | |
---|---|
api‑key | string Ключ API, предоставляемый при создании потока, должен быть действителен для сети издателя. Вместо предоставления его в теле запроса ключ API можно передать в заголовке авторизации HTTP в следующем формате: Authorization: DCLKDAI key="<api-key>" |
Параметры пути
Параметры | |
---|---|
content-source | string Идентификатор CMS потока. |
video-id | string Идентификатор видео потока. |
Тело запроса
Тело запроса имеет тип application/x-www-form-urlencoded
и содержит следующие параметры:
Параметры | ||
---|---|---|
dai-ssb | Необязательный | Установите значение |
Параметры таргетинга DFP | Необязательный | Дополнительные параметры таргетинга. |
Переопределить параметры потока | Необязательный | Переопределить значения по умолчанию для параметра создания потока. |
HMAC-аутентификация | Необязательный | Аутентификация с использованием токена на основе HMAC. |
Тело ответа
В случае успеха тело ответа содержит новый Stream
. Для потоков маяков на стороне сервера этот Stream
содержит только stream_id
stream_manifest
.
Открытое измерение
Поле Verifications
содержит информацию для проверки открытого измерения для потоков маяков не на стороне сервера. Verifications
содержит один или несколько элементов Verification
, в которых перечислены ресурсы и метаданные, необходимые для проверки воспроизведения креатива с помощью стороннего кода измерения. Поддерживается только JavaScriptResource
. Для получения дополнительной информации посетите техническую лабораторию IAB и спецификацию VAST 4.1 .
Метод: проверка носителя
После того как вы встретите идентификатор рекламного носителя во время воспроизведения, немедленно сделайте запрос, используя media_verification_url
из конечной точки stream
. media_verification_url
— это абсолютный путь. Запросы на проверку носителя не требуются для потоков маяков на стороне сервера, где сервер инициирует проверку носителя.
Запросы к конечной точке media verification
идемпотентны.
Методы | |
---|---|
media verification | GET {media_verification_url}/{ad_media_id} Уведомляет API о событии проверки носителя. |
HTTP-запрос
GET {media-verification-url}/{ad-media-id}
Тело ответа
media verification
возвращает следующие ответы:
-
HTTP/1.1 204 No Content
, если проверка носителя прошла успешно и все пинги отправлены. -
HTTP/1.1 404 Not Found
если запрос не может проверить носитель из-за неправильного форматирования URL-адреса или истечения срока его действия. -
HTTP/1.1 404 Not Found
если предыдущий запрос на проверку этого идентификатора был успешным. -
HTTP/1.1 409 Conflict
, если в это время другой запрос уже отправляет пинги.
Идентификаторы рекламных носителей (HLS)
Идентификаторы рекламных носителей будут закодированы в синхронизированных метаданных HLS с использованием ключа TXXX
, зарезервированного для кадров «определяемой пользователем текстовой информации». Содержимое фрейма будет незашифрованным и всегда будет начинаться с текста "google_"
.
Все текстовое содержимое фрейма должно быть добавлено к media_verification_url для каждого запроса на проверку объявления.
Идентификаторы рекламных носителей (DASH)
Идентификаторы рекламных носителей будут вставлены в манифест с помощью элемента EventStream
DASH.
Каждый EventStream
будет иметь URI идентификатора схемы urn:google:dai:2018
. Они будут содержать события с атрибутом messageData
, содержащим идентификатор рекламного носителя, начинающийся с “google_”
. Все содержимое атрибута messageData
должно быть добавлено к media_verification_url для каждого запроса на проверку объявления.
Данные ответа
Транслировать
Stream используется для рендеринга списка всех ресурсов для вновь созданного потока в формате JSON.JSON-представление |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
Поля | |
---|---|
stream_id | string Идентификатор потока. |
total_duration | number Продолжительность потока в секундах. |
content_duration | number Продолжительность контента без рекламы в секундах. |
valid_for | string Продолжительность потока действительна в формате «00ч00м00с». |
valid_until | string Дата, до которой поток действителен, в формате RFC 3339. |
subtitles | [object(Subtitle)] Список субтитров. Опускается, если пусто. Только ЗОЖ. |
hls_master_playlist | string (УСТАРЕЛО) URL-адрес основного плейлиста HLS. Используйте поток_манифест. Только ЗОЖ. |
stream_manifest | string Манифест потока. Соответствует основному плейлисту в HLS и MPD в DASH. Это единственное поле, помимо «stream_id», которое присутствует в ответе при создании потока маяков на стороне сервера. |
media_verification_url | string URL-адрес проверки носителя. |
apple_tv | object(AppleTV) Дополнительная информация, относящаяся к устройствам AppleTV. Только ЗОЖ. |
ad_breaks | [object(AdBreak)] Список рекламных брейков. Опускается, если пусто. |
AppleTV
AppleTV содержит информацию, специфичную для устройств Apple TV.JSON-представление |
---|
{ "interstitials_url": string, } |
Поля | |
---|---|
interstitials_url | string URL межстраничных объявлений. |
Рекламная пауза
AdBreak описывает одну рекламную паузу в потоке. Он содержит позицию, продолжительность, тип (середина/до/после) и список объявлений.JSON-представление |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
Поля | |
---|---|
type | string Допустимые типы перерывов: в середине, перед и после. |
start | number Позиция в стриме, с которой начинается перерыв, в секундах. |
duration | number Продолжительность рекламной паузы в секундах. |
ads | [object(Ad)] Список объявлений. Опускается, если пусто. |
Объявление
Объявление описывает рекламу в потоке. Он содержит положение объявления в паузе, его продолжительность и некоторые дополнительные метаданные.JSON-представление |
---|
{ "seq": number, "start": number, "duration": number, "title": string, "description": string, "advertiser": string, "ad_system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, "clickthrough_url": string, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), "skip_metadata": object(SkipMetadata), } |
Поля | |
---|---|
seq | number Положение объявления в перерыве. |
start | number Позиция в ленте, с которой начинается реклама, в секундах. |
duration | number Продолжительность рекламы в секундах. |
title | string Необязательное название объявления. |
description | string Необязательное описание объявления. |
advertiser | string Необязательный идентификатор рекламодателя. |
ad_system | string Дополнительная рекламная система. |
ad_id | string Необязательный идентификатор объявления. |
creative_id | string Необязательный идентификатор объявления. |
creative_ad_id | string Необязательный идентификатор креативного объявления. |
deal_id | string Необязательный идентификатор сделки. |
clickthrough_url | string Необязательный URL перехода по клику. |
icons | [object(Icon)] Список значков, опускается, если он пуст. |
wrappers | [object(Wrapper)] Список оберток. Опускается, если пусто. |
events | [object(Event)] Список событий в объявлении. |
verifications | [object(Verification)] Дополнительные записи проверки Open Measurement, в которых перечислены ресурсы и метаданные, необходимые для выполнения стороннего кода измерения для проверки воспроизведения креатива. |
universal_ad_id | object(UniversalAdID) Необязательный универсальный идентификатор объявления. |
companions | [object(Companion)] Дополнительные сопутствующие объявления, которые могут отображаться вместе с этим объявлением. |
interactive_file | object(InteractiveFile) Необязательный интерактивный креатив (SIMID), который должен отображаться во время воспроизведения рекламы. |
skip_metadata | object(SkipMetadata) Необязательные метаданные для пропускаемой рекламы. Если этот параметр установлен, это означает, что объявление можно пропустить, и включает инструкции по обработке пользовательского интерфейса пропуска и событий отслеживания. |
Событие
Событие содержит тип события и время его представления.JSON-представление |
---|
{ "time": number, "type": string, } |
Поля | |
---|---|
time | number Время презентации этого мероприятия. |
type | string Тип этого события. |
Субтитры
Субтитры описывают дорожку субтитров для видеопотока. Он хранит два формата субтитров: TTML и WebVTT. Атрибут TTMLPath содержит URL-адрес дополнительного файла TTML, а атрибут WebVTTPath аналогичным образом содержит URL-адрес дополнительного файла WebVTT.JSON-представление |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
Поля | |
---|---|
language | string Код языка, например «en» или «de». |
language_name | string Описательное название языка. Он различает конкретный набор субтитров, если для одного и того же языка существует несколько наборов. |
ttml | string Необязательный URL-адрес дополнительного файла TTML. |
webvtt | string Необязательный URL-адрес дополнительного файла WebVTT. |
ПропуститьМетаданные
SkipMetadata предоставляет информацию, необходимую клиентам для обработки событий пропуска для пропускаемой рекламы.JSON-представление |
---|
{ "offset": number, "tracking_url": string, } |
Поля | |
---|---|
offset | number Смещение указывает время в секундах, в течение которого игрок должен подождать до появления кнопки пропуска в рекламе. Опускается, если не указано в VAST. |
tracking_url | string TrackingURL содержит URL-адрес, который необходимо проверить при событии пропуска. |
Икона
Значок содержит информацию о значке VAST.JSON-представление |
---|
{ "click_data": object(ClickData), "creative_type": string, "click_fallback_images": [object(FallbackImage)], "height": int32, "width": int32, "resource": string, "type": string, "x_position": string, "y_position": string, "program": string, "alt_text": string, } |
Поля | |
---|---|
click_data | object(ClickData) |
creative_type | string |
click_fallback_images | [object(FallbackImage)] |
height | int32 |
width | int32 |
resource | string |
type | string |
x_position | string |
y_position | string |
program | string |
alt_text | string |
КликДанные
ClickData содержит информацию о кликах по значку.JSON-представление |
---|
{ "url": string, } |
Поля | |
---|---|
url | string |
Резервное изображение
FallbackImage содержит информацию о резервном изображении VAST.JSON-представление |
---|
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } |
Поля | |
---|---|
creative_type | string |
height | int32 |
width | int32 |
resource | string |
alt_text | string |
обертка
Обертка содержит информацию об объявлении-обертке. Он не включает идентификатор сделки, если он не существует.JSON-представление |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
Поля | |
---|---|
system | string Идентификатор рекламной системы. |
ad_id | string Идентификатор объявления, используемый для объявления-контейнера. |
creative_id | string Идентификатор объявления, используемый для объявления-контейнера. |
creative_ad_id | string Идентификатор креативного объявления, используемый для объявления-контейнера. |
deal_id | string Необязательный идентификатор сделки для объявления-контейнера. |
Проверка
Проверка содержит информацию для открытого измерения, которая облегчает стороннее измерение видимости и проверки. В настоящее время поддерживаются только ресурсы JavaScript. См. https://iabtechlab.com/standards/open-measurement-sdk/.JSON-представление |
---|
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } |
Поля | |
---|---|
vendor | string Поставщик проверки. |
java_script_resources | [object(JavaScriptResource)] Список ресурсов JavaScript для проверки. |
tracking_events | [object(TrackingEvent)] Список событий отслеживания для проверки. |
parameters | string Непрозрачная строка, передаваемая в код проверки начальной загрузки. |
JavaScriptРесурс
JavaScriptResource содержит информацию для проверки через JavaScript.JSON-представление |
---|
{ "script_url": string, "api_framework": string, "browser_optional": boolean, } |
Поля | |
---|---|
script_url | string URI для полезных данных JavaScript. |
api_framework | string APIFramework — это имя платформы видео, использующей код проверки. |
browser_optional | boolean Можно ли запустить этот скрипт вне браузера. |
Событие отслеживания
TrackingEvent содержит URL-адреса, которые клиент должен проверять в определенных ситуациях.JSON-представление |
---|
{ "event": string, "uri": string, } |
Поля | |
---|---|
event | string Тип события отслеживания. |
uri | string Событие отслеживания, которое необходимо проверить. |
Универсальный идентификатор рекламы
UniversalAdID используется для предоставления уникального идентификатора креатива, который сохраняется во всех рекламных системах.JSON-представление |
---|
{ "id_value": string, "id_registry": string, } |
Поля | |
---|---|
id_value | string Универсальный рекламный идентификатор выбранного креатива для объявления. |
id_registry | string Строка, используемая для идентификации URL-адреса веб-сайта реестра, на котором каталогизирован универсальный идентификатор объявления выбранного креатива. |
Компаньон
Сопутствующий контент содержит информацию о сопутствующих объявлениях, которые могут отображаться вместе с рекламой.JSON-представление |
---|
{ "click_data": object(ClickData), "creative_type": string, "height": int32, "width": int32, "resource": string, "type": string, "ad_slot_id": string, "api_framework": string, "tracking_events": [object(TrackingEvent)], } |
Поля | |
---|---|
click_data | object(ClickData) Данные о кликах для этого сопутствующего баннера. |
creative_type | string Атрибут CreativeType в узле <StaticResource> в VAST, если он является сопутствующим типом static. |
height | int32 Высота этого компаньона в пикселях. |
width | int32 Ширина этого компаньона в пикселях. |
resource | string Для статических сопутствующих баннеров и сопутствующих баннеров iframe это будет URL-адрес для загрузки и отображения. Для сопутствующих HTML-кодов это будет фрагмент HTML, который должен отображаться в качестве сопутствующего. |
type | string Тип этого компаньона. Это может быть статический, iframe или HTML. |
ad_slot_id | string Идентификатор слота для этого компаньона. |
api_framework | string Платформа API для этого компаньона. |
tracking_events | [object(TrackingEvent)] Список событий отслеживания для этого компаньона. |
ИнтерактивныйФайл
InteractiveFile содержит информацию об интерактивном креативе (т. е. SIMID), который должен отображаться во время воспроизведения рекламы.JSON-представление |
---|
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } |
Поля | |
---|---|
resource | string URL-адрес интерактивного объявления. |
type | string MIME-тип файла, предоставленного в качестве ресурса. |
variable_duration | boolean Может ли это объявление запросить продление срока действия. |
ad_parameters | string Значение узла <AdParameters> в VAST. |