API динамической вставки рекламы позволяет запрашивать и отслеживать линейные (LIVE) потоки DAI.
Сервис: dai.google.com.
Все URI ниже относятся к https://dai.google.com
Метод: поток
Методы | |
---|---|
stream | POST /linear/v1/hls/event/{assetKey}/stream Создает поток DAI для данного идентификатора события. |
HTTP-запрос
POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream
Заголовок запроса
Параметры | |
---|---|
api‑key | string Ключ API, предоставляемый при создании потока, должен быть действителен для сети издателя. Вместо предоставления его в теле запроса ключ API можно передать в заголовке авторизации HTTP в следующем формате: Authorization: DCLKDAI key="<api-key>" |
Параметры пути
Параметры | |
---|---|
assetKey | string Идентификатор события потока. |
Тело запроса
Тело запроса имеет тип application/x-www-form-urlencoded
и содержит следующие параметры:
Параметры | ||
---|---|---|
dai-ssb | Необязательный | Установите значение |
Параметры таргетинга DFP | Необязательный | Дополнительные параметры таргетинга. |
Переопределить параметры потока | Необязательный | Переопределить значения по умолчанию для параметра создания потока. |
HMAC-аутентификация | Необязательный | Аутентификация с использованием токена на основе HMAC. |
Тело ответа
В случае успеха тело ответа содержит новый Stream
. Для потоков маяков на стороне сервера этот Stream
содержит только stream_id
stream_manifest
.
Открытое измерение
API DAI содержит информацию для проверки Open Measurement в поле Verifications
. Это поле содержит один или несколько элементов Verification
, в которых перечислены ресурсы и метаданные, необходимые для выполнения стороннего кода измерения для проверки воспроизведения креатива. Поддерживается только JavaScriptResource
. Для получения дополнительной информации посетите техническую лабораторию IAB и спецификацию VAST 4.1 .
Метод: проверка носителя
Обнаружив идентификатор рекламного носителя во время воспроизведения, немедленно сделайте запрос, используя media_verification_url , полученный из конечной точки потока , указанной выше. Эти запросы не нужны для потоков маяков на стороне сервера, где сервер инициирует проверку мультимедиа.
Запросы к конечной точке media verification
идемпотентны.
Методы | |
---|---|
media verification | GET /{media_verification_url}/{ad_media_id} Уведомляет API о событии проверки носителя. |
HTTP-запрос
GET https://{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_"
.
Все текстовое содержимое фрейма должно быть добавлено к URL-адресу проверки объявления перед отправкой каждого запроса на проверку объявления.
Метод: метаданные
Конечная точка метаданных в metadata_url
возвращает информацию, используемую для создания пользовательского интерфейса рекламы. Конечная точка метаданных недоступна для потоков маяков на стороне сервера, где сервер отвечает за инициацию проверки рекламного носителя.
Методы | |
---|---|
metadata | GET /{metadata_url}/{ad-media-id} GET /{metadata_url} Получает информацию о метаданных объявления. |
HTTP-запрос
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
Тело ответа
В случае успеха ответ возвращает экземпляр PodMetadata
.
Работа с метаданными
Метаданные состоят из трех отдельных разделов: tags
, ads
и рекламные breaks
. Точкой входа в данные является раздел tags
. Далее просмотрите теги и найдите первую запись, имя которой является префиксом идентификатора рекламного носителя , найденного в видеопотоке. Например, у вас может быть идентификатор рекламного носителя, который выглядит так:
google_1234567890
Затем вы найдете объект тега с именем google_12345
. В данном случае он соответствует идентификатору вашего рекламного носителя. Найдя правильный объект префикса рекламного носителя, вы сможете найти идентификаторы объявлений, идентификаторы рекламных пауз и тип события. Идентификаторы рекламы затем используются для индексации объектов ads
, а идентификаторы рекламных пауз используются для индексации объектов breaks
.
Данные ответа
Транслировать
Stream используется для отображения списка ресурсов для вновь созданного потока в формате JSON.JSON-представление |
---|
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } |
Поля | |
---|---|
stream_id | string Идентификатор потока GAM. |
stream_manifest | string URL-адрес манифеста потока, используемый для получения многовариантного списка воспроизведения в HLS или MPD в DASH. |
hls_master_playlist | string (УСТАРЕЛО) URL-адрес многовариантного плейлиста HLS. Вместо этого используйте «stream_manifest». |
media_verification_url | string URL-адрес проверки мультимедиа, используемый в качестве базовой конечной точки для отслеживания событий воспроизведения. |
metadata_url | string URL-адрес метаданных, используемый для периодического опроса информации о предстоящих рекламных событиях потокового вещания. |
session_update_url | string URL-адрес обновления сеанса, используемый для обновления параметров таргетинга для этого потока. Исходные значения параметров таргетинга фиксируются во время первоначального запроса на создание потока. |
polling_frequency | number Частота опроса в секундах при запросе Metadata_url или Heartbeat_url. |
Метаданные Pod
PodMetadata содержит метаданные о рекламе, рекламных паузах и тегах идентификаторов мультимедиа.JSON-представление |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
Поля | |
---|---|
tags | map[string, object(TagSegment)] Карта сегментов тегов, индексированных по префиксу тега. |
ads | map[string, object(Ad)] Карта объявлений, проиндексированных по идентификатору объявления. |
ad_breaks | map[string, object(AdBreak)] Карта рекламных пауз, проиндексированная по идентификатору рекламной паузы. |
ТегСегмент
TagSegment содержит ссылку на рекламу, ее рекламную паузу и тип события. TagSegment с type="progress" не должен отправляться на конечную точку проверки рекламного носителя.JSON-представление |
---|
{ "ad": string, "ad_break_id": string, "type": string, } |
Поля | |
---|---|
ad | string Идентификатор объявления этого тега. |
ad_break_id | string Идентификатор рекламной паузы этого тега. |
type | string Тип события этого тега. |
Рекламная пауза
AdBreak описывает одну рекламную паузу в потоке. Он содержит продолжительность, тип (в середине/до/после) и количество объявлений.JSON-представление |
---|
{ "type": string, "duration": number, "expected_duration": number, "ads": number, } |
Поля | |
---|---|
type | string Допустимые типы перерывов: до, в середине и после. |
duration | number Общая продолжительность рекламы для этой рекламной паузы в секундах. |
expected_duration | number Ожидаемая продолжительность рекламной паузы (в секундах), включая всю рекламу и любую рекламную паузу. |
ads | number Количество рекламы в рекламной паузе. |
Объявление
Объявление описывает рекламу в потоке.JSON-представление |
---|
{ "ad_break_id": string, "position": 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, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
Поля | |
---|---|
ad_break_id | string Идентификатор рекламной паузы этого объявления. |
position | number Позиция этого объявления в рекламной паузе, начиная с 1. |
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 перехода по клику. |
click_tracking_urls | string Необязательные URL-адреса отслеживания кликов. |
verifications | [object(Verification)] Дополнительные записи проверки Open Measurement, в которых перечислены ресурсы и метаданные, необходимые для выполнения стороннего кода измерения для проверки воспроизведения креатива. |
slate | boolean Необязательное логическое значение, указывающее, что текущая запись является запланированной. |
icons | [object(Icon)] Список значков, опускается, если он пуст. |
wrappers | [object(Wrapper)] Список оберток. Если он пуст, опускается. |
universal_ad_id | object(UniversalAdID) Необязательный универсальный идентификатор объявления. |
extensions | string Необязательный список всех узлов <Extension> в VAST. |
companions | [object(Companion)] Дополнительные сопутствующие объявления, которые могут отображаться вместе с этим объявлением. |
interactive_file | object(InteractiveFile) Необязательный интерактивный креатив (SIMID), который должен отображаться во время воспроизведения рекламы. |
Икона
Значок содержит информацию о значке 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. |