API динамической вставки рекламы VOD

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 для данного источника контента и идентификатора видео.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

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

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

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