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

API динамической вставки рекламы позволяет запрашивать и отслеживать потоки видео по запросу (VOD) с использованием технологии DAI. Поддерживаются потоки HLS и DASH.

Сервис: dai.google.com

Путь к методу stream указывается относительно https://dai.google.com

Метод: поток

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

Заголовок запроса

Authorization: DCLKDAI key="<api-key>"

Параметры пути

Текст запроса

Тело запроса имеет тип application/x-www-form-urlencoded и содержит следующие параметры:

Ответный текст

В случае успеха тело ответа содержит новый Stream . Для потоков, отправляемых на стороне сервера, этот Stream содержит только поля stream_id и stream_manifest .

Открытое измерение

Поле Verifications содержит информацию для проверки Open Measurement для потоков, не использующих серверную передачу сигналов. Поле Verifications содержит один или несколько элементов Verification , в которых перечислены ресурсы и метаданные, необходимые для проверки воспроизведения креативов с помощью стороннего кода измерения. Поддерживается только JavaScriptResource . Для получения дополнительной информации см. IAB Tech Lab и спецификацию VAST 4.1 .

Метод: проверка СМИ

После обнаружения идентификатора рекламного медиафайла во время воспроизведения, немедленно отправьте запрос, используя media_verification_url , с конечной точки stream . media_verification_url — это абсолютный путь. Запросы на проверку медиафайлов не требуются для потоков, передающих сигналы на стороне сервера, где проверку медиафайлов инициирует сам сервер.

Запросы к конечной точке media verification являются идемпотентными.

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 Timed Metadata с использованием ключа TXXX , зарезервированного для фреймов с "текстовой информацией, определяемой пользователем". Содержимое фрейма будет незашифрованным и всегда будет начинаться с текста "google_" .

Для каждого запроса на подтверждение рекламы необходимо добавить все текстовое содержимое фрейма в поле media_verification_url .

Идентификаторы рекламных медиа (DASH)

Идентификаторы рекламных медиафайлов будут добавлены в манифест с помощью элемента EventStream из библиотеки DASH.

Каждый EventStream будет иметь URI с идентификатором схемы urn:google:dai:2018 . Они будут содержать события с атрибутом messageData , включающим идентификатор рекламного носителя, начинающийся с "google_" . Всё содержимое атрибута messageData должно быть добавлено к media_verification_url для каждого запроса на подтверждение рекламы.

Данные ответа

Транслировать

{
  "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)],
}

AppleTV

{
  "interstitials_url": string,
}

AdBreak

{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}

Объявление

{
  "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),
  "extensions": [],
}

Событие

{
  "time": number,
  "type": string,
}

Субтитры

{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}

SkipMetadata

{
  "offset": number,
  "tracking_url": 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

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Упаковка

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

Проверка

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

Отслеживание событий

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

Спутник

{
  "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)],
}

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

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}

API динамической вставки рекламы позволяет запрашивать и отслеживать потоки видео по запросу (VOD) с использованием технологии DAI. Поддерживаются потоки HLS и DASH.

Сервис: dai.google.com

Путь к методу stream указывается относительно https://dai.google.com

Метод: поток

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

Заголовок запроса

Authorization: DCLKDAI key="<api-key>"

Параметры пути

Текст запроса

Тело запроса имеет тип application/x-www-form-urlencoded и содержит следующие параметры:

Ответный текст

В случае успеха тело ответа содержит новый Stream . Для потоков, отправляемых на стороне сервера, этот Stream содержит только поля stream_id и stream_manifest .

Открытое измерение

Поле Verifications содержит информацию для проверки Open Measurement для потоков, не использующих серверную передачу сигналов. Поле Verifications содержит один или несколько элементов Verification , в которых перечислены ресурсы и метаданные, необходимые для проверки воспроизведения креативов с помощью стороннего кода измерения. Поддерживается только JavaScriptResource . Для получения дополнительной информации см. IAB Tech Lab и спецификацию VAST 4.1 .

Метод: проверка СМИ

После обнаружения идентификатора рекламного медиафайла во время воспроизведения, немедленно отправьте запрос, используя media_verification_url , с конечной точки stream . media_verification_url — это абсолютный путь. Запросы на проверку медиафайлов не требуются для потоков, передающих сигналы на стороне сервера, где проверку медиафайлов инициирует сам сервер.

Запросы к конечной точке media verification являются идемпотентными.

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 Timed Metadata с использованием ключа TXXX , зарезервированного для фреймов с "текстовой информацией, определяемой пользователем". Содержимое фрейма будет незашифрованным и всегда будет начинаться с текста "google_" .

Для каждого запроса на подтверждение рекламы необходимо добавить все текстовое содержимое фрейма в поле media_verification_url .

Идентификаторы рекламных медиа (DASH)

Идентификаторы рекламных медиафайлов будут добавлены в манифест с помощью элемента EventStream из библиотеки DASH.

Каждый EventStream будет иметь URI с идентификатором схемы urn:google:dai:2018 . Они будут содержать события с атрибутом messageData , включающим идентификатор рекламного носителя, начинающийся с "google_" . Всё содержимое атрибута messageData должно быть добавлено к media_verification_url для каждого запроса на подтверждение рекламы.

Данные ответа

Транслировать

{
  "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)],
}

AppleTV

{
  "interstitials_url": string,
}

AdBreak

{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}

Объявление

{
  "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),
  "extensions": [],
}

Событие

{
  "time": number,
  "type": string,
}

Субтитры

{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}

SkipMetadata

{
  "offset": number,
  "tracking_url": 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

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Упаковка

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

Проверка

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

Отслеживание событий

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

Спутник

{
  "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)],
}

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

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}