Модуль динамической вставки объявлений с API в реальном времени

API динамической вставки рекламы позволяет запрашивать и отслеживать прямые трансляции DAI.

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

Все URI относятся к https://dai.google.com .

Метод: поток

Методы
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Регистрирует модуль DAI DAI, обслуживающий сеанс прямой трансляции.

HTTP-запрос 

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

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

Параметры
network_code string

Сетевой код Google Ad Manager издателя.

custom_asset_key string

Пользовательский идентификатор, связанный с этим событием в Google Ad Manager.

Тело запроса

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

Параметры
Параметры таргетинга DFP Необязательный Дополнительные параметры таргетинга.
Переопределить параметры потока Необязательный Переопределить значения по умолчанию для параметра создания потока.
HMAC-аутентификация Необязательный Аутентификация с использованием токена на основе HMAC.

Тело ответа

В случае успеха тело ответа содержит новый объект Stream .

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

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

Метод: сегмент модуля

Методы
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

Создает поток DAI для данного идентификатора события.

HTTP-запрос 

GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

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

Параметры
network_code string

Сетевой код Google Ad Manager издателя.

custom_asset_key string

Пользовательский идентификатор, связанный с этим событием в Google Ad Manager.

pod_identifier

Поддерживаются следующие форматы:

pod/{integer}

Числовой идентификатор текущей рекламной паузы. Идентификаторы рекламных блоков назначаются постепенно для каждой рекламной паузы, начиная с 1 .

ad_break_id/{string}

Строковый идентификатор текущей рекламной паузы.

profile_name string

Название запрошенного профиля кодирования DAI Google Ad Manager . Профиль кодирования должен быть одним из настроенных профилей кодирования для выбранного события.

segment_number integer

Индекс запрошенного сегмента в текущем рекламном пакете, начиная с нуля.

segment_format string

Расширение файла, связанное с запрошенным форматом сегмента. Принимаемые расширения: ts , mp4 , vtt , aac , ac3 или eac3 .

Параметры запроса

Параметры
stream_id необходимый string

Идентификатор потока для сеанса текущего пользователя. Это значение возвращается в результате успешного запроса к конечной точке stream .

sd required 1 integer

Длительность запрошенного сегмента в миллисекундах.

so необязательный

Смещение запрошенного сегмента внутри рекламного модуля в миллисекундах. Если вы опустите параметр so , он будет рассчитываться путем умножения продолжительности сегмента на номер сегмента.

pd требуется 2 integer

Продолжительность рекламного блока в миллисекундах.

auth-token необходимый string

Подписанный токен HMAC в кодировке URL для текущего рекламного модуля.

last необязательный boolean

Указывает последний сегмент рекламной паузы. Опустите этот параметр для всех остальных сегментов.

scte35 необязательный string

Сигнал SCTE-35 в кодировке Base64 для этой рекламной паузы.

cust_params необязательный string

Набор пар ключ-значение, используемый для таргетинга кампании Менеджера рекламы. Эти пары должны быть представлены в виде строки запроса в кодировке URL.

Пример:
Параметры
  • раздел = sports
  • страница = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Сноски

  1. sd не требуется для сегментов инициализации. ↩
  2. pd не требуется для мероприятий с включенными бесконечными рекламными паузами. ↩

Пример

ПОЛУЧИТЕ https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd =10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

ПОЛУЧИТЕ https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd =30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

Тело ответа

В случае успеха телом ответа будет воспроизводимый сегмент потока, соответствующий формату и параметрам, указанным в запросе.

Метод: манифест модуля HLS.

Получает манифест рекламного модуля HLS для прямой трансляции, готовый для загрузки и воспроизведения клиентским видеопроигрывателем.

Методы
GET GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/pod/{pod_id}.m3u8;

API для получения многовариантного плейлиста HLS для рекламного модуля.

HTTP-запрос 

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

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

Параметры
network_code string

Сетевой код Google Ad Manager издателя.

custom_asset_key string

Пользовательский идентификатор, связанный с этим событием в Google Ad Manager.

pod_id integer

Числовой идентификатор текущей рекламной паузы. Идентификаторы рекламных блоков назначаются постепенно для каждой рекламной паузы, начиная с 1 .

Параметры запроса

Параметры
stream_id Необходимый string

Идентификатор потока для сеанса текущего пользователя. Это значение возвращается в результате успешного запроса к конечной точке stream .

pd Необходимый integer

Продолжительность рекламного блока в миллисекундах.

scte35 необязательный string

Сигнал SCTE-35 в кодировке Base64 для этой рекламной паузы.

cust_params необязательный string

Набор пар ключ-значение, используемый для таргетинга кампании Менеджера рекламы. Эти пары должны быть представлены в виде строки запроса в кодировке URL.

Пример:
Параметры
  • раздел = sports
  • страница = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Тело ответа

В случае успеха тело ответа представляет собой многовариантный список воспроизведения HLS.

Метод: манифест модуля DASH.

Получает манифест рекламного модуля MPEG-DASH для прямой трансляции, готовый для загрузки и воспроизведения клиентским видеопроигрывателем.

Методы
GET GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd

API для получения плейлиста MPEG-DASH mpd для рекламного модуля.

HTTP-запрос 

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

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

Параметры
network_code string

Сетевой код Google Ad Manager издателя.

custom_asset_key string

Пользовательский идентификатор, связанный с этим событием в Google Ad Manager.

stream_id string

Идентификатор потока для сеанса текущего пользователя. Это значение возвращается в результате успешного запроса к конечной точке stream .

pod_id integer

Числовой идентификатор текущей рекламной паузы. Идентификаторы рекламных блоков назначаются постепенно для каждой рекламной паузы, начиная с 1 .

Параметры запроса

Параметры
pd Необходимый integer

Продолжительность рекламного блока в миллисекундах.

scte35 необязательный string

Сигнал SCTE-35 в кодировке Base64 для этой рекламной паузы.

cust_params необязательный string

Набор пар ключ-значение, используемый для таргетинга кампании Менеджера рекламы. Эти пары должны быть представлены в виде строки запроса в кодировке URL.

Пример:
Параметры
  • раздел = sports
  • страница = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Тело ответа

В случае успеха тело ответа представляет собой список воспроизведения MPEG-DASH mpd.

Метод: шаблон периода модуля DASH.

Методы
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Запрашивает шаблон периода DASH из Google Ad Manager. Этот шаблон содержит макросы, которые необходимо заполнить параметрами потока. Как только эти макросы будут заполнены, шаблон станет периодом рекламной паузы и его можно будет встроить в манифест DASH.

HTTP-запрос 

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

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

Параметры
network_code string

Сетевой код Google Ad Manager издателя.

custom_asset_key string

Пользовательский идентификатор, связанный с этим событием в Google Ad Manager.

Параметры запроса

Параметры
stream_id необходимый string

Идентификатор потока для сеанса текущего пользователя. Это значение возвращается в результате успешного запроса к конечной точке stream .

Тело ответа

В случае успеха тело ответа содержит новый объект PodTemplateResponse .

Метод: проверка носителя

Обнаружив идентификатор рекламного носителя во время воспроизведения, немедленно сделайте запрос, используя 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 или emsg для файлов mp4. Идентификаторы рекламных носителей всегда начинаются со строки 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,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Поля
stream_id string

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

URL-адрес проверки мультимедиа, используемый в качестве базовой конечной точки для отслеживания событий воспроизведения.
metadata_url string

URL-адрес метаданных, используемый для периодического опроса информации о предстоящих рекламных событиях потокового вещания.
session_update_url string

URL-адрес обновления сеанса, используемый для обновления параметров таргетинга для этого потока. Исходные значения параметров таргетинга фиксируются во время первоначального запроса на создание потока.
heartbeat_url string

URL-адрес контрольного сигнала, используемый для поддержания активности потока маяков на стороне сервера. Он должен проверяться каждые {PollingFrequency} секунд. Заполняется для потоков маяков на стороне сервера.
polling_frequency number

Частота опроса в секундах при запросе Metadata_url или Heartbeat_url.
pod_manifest_url string

Шаблон URL-адреса манифеста модуля используется для создания URL-адреса для получения манифеста модуля потока, соответствующего URL-адресу многовариантного списка воспроизведения в HLS или MPD в DASH. Заполняется для событий прямой трансляции с типом динамической вставки рекламы POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Формат манифеста — это формат манифеста, полученного из pod_manifest_url, Dash или hls.

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

PodTemplateResponse

PodTemplateResponse представляет собой полезную нагрузку JSON, возвращаемую VTP для сшивания модулей.
JSON-представление
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Поля
dash_period_template string

DashPeriodTemplate — это XML-шаблон для периода, который необходимо заполнить соответствующими данными перед сшивкой.
segment_duration_ms int64

SegmentDurationMS — продолжительность сегментов периода в миллисекундах.

Икона

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