Линейный 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

Идентификатор потока.
stream_manifest string

Манифест потока, соответствующий основному списку воспроизведения в HLS или MPD в DASH. Это единственное поле, помимо «stream_id», которое присутствует в ответе при создании потока маяков на стороне сервера.
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

Рекомендуемая частота опроса 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

Тип события отслеживания. В настоящее время единственным вариантом является «verificationNotExecuted», как указано в спецификации VAST 4.1.
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,
}
Поля
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.

ИнтерактивныйФайл

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.