Линейный API динамической вставки объявлений

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 Необязательный

Установите значение true , чтобы создать поток маяков на стороне сервера. По умолчанию установлено значение false . Отслеживание потока по умолчанию инициируется клиентом и проверяется на стороне сервера.

Параметры таргетинга 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.