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),
}
Поля
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), который должен отображаться во время воспроизведения рекламы.

Событие

Событие содержит тип события и время его представления.
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.

Икона

Значок содержит информацию о значке 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.