Модуль динамической вставки объявлений с 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-под, обслуживающий сессию прямой трансляции.

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 Tech Lab и спецификацию 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}

Строковый идентификатор текущей рекламной паузы. Любой неизвестный идентификатор рекламной паузы, предоставленный этому адресу, создаст новую рекламную паузу для прямой трансляции.

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.
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

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • pod_id или ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp
last необязательный boolean

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

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

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

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

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

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

Сноски

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

Пример

GET 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

GET 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_identifier}.m3u8;

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

HTTP-запрос 

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

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

Параметры
network_code string

Код рекламной сети Google Ad Manager издателя.

custom_asset_key string

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

pod_identifier

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

pod/{integer}

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

ad_break_id/{string}

Строковый идентификатор текущей рекламной паузы. Любой неизвестный идентификатор рекламной паузы, предоставленный этому адресу, создаст новую рекламную паузу для прямой трансляции.

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.

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

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

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

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

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

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

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

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

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

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

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • pod_id или ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp

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

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

Метод: манифест DASH-пода

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

Методы
GET GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/{pod_identifier}/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_identifier

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

pod/{integer}

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

ad_break_id/{string}

Строковый идентификатор текущей рекламной паузы. Любой неизвестный идентификатор рекламной паузы, предоставленный этому адресу, создаст новую рекламную паузу для прямой трансляции.

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.

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

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

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

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

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

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

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

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

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • pod_id или ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp

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

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

Метод: Шаблон периода DASH-под

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

Запрашивает у Google Ad Manager шаблон периода DASH. Этот шаблон содержит макросы, которые необходимо заполнить параметрами вашего потока. После заполнения этих макросов шаблон становится периодом для вашей рекламной паузы и может быть интегрирован в ваш манифест 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 .

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

Версия шаблона. По умолчанию — 0 Указывает версию шаблона пода, которую необходимо вернуть.

  • 0 : Запрашивает шаблон, использующий идентификатор последовательности пода.
  • 1 : Запрашивает шаблон, поддерживающий как идентификаторы последовательности подов, так и идентификаторы рекламных пауз.

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

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

Метод: Метаданные о времени показа рекламного блока

Методы
ad pod timing metadata GET /linear/pods/v1/adv/network/{network_code}/custom_asset/{custom_asset_key}/pod.json

Получает метаданные о времени показа рекламных блоков.

HTTP-запрос 

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

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

Параметры
network_code string

Код рекламной сети Google Ad Manager издателя.

custom_asset_key string

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

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

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

Идентификатор потока Ad Manager из клиентского приложения видеоплеера.

ad_break_id необходимый string

Следующая заставка рекламной паузы.

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

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.
  • Идентификатор рекламной паузы preroll зарезервирован для получения рекламного блока preroll. Он не может быть использован для идентификации какого-либо другого рекламного блока.
auth-token необходимый string

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp
timeout необязательный integer

Количество миллисекунд, в течение которых DAI может блокировать этот запрос в ожидании решения по рекламе. Используйте этот параметр для запросов, которые должны вернуть заполненную рекламу с первого раза, например, для рекламных пауз перед началом показа.

Если время ожидания превышено, запрос возвращает статус «ожидание».

Если параметр timeout указан, он должен находиться в диапазоне от 1000 до 15000 миллисекунд. Если он опущен, задержка ответа в ожидании решения по рекламе не происходит.

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

Установите значение true , чтобы указать DAI, что это последний запрос, который VTP готов отправить для этого рекламного блока. Если решение о показе рекламы еще не принято (по истечении необязательного времени ожидания), DAI навсегда вернет рекламный блок для этого запроса.

По умолчанию — false .

Параметры принятия решения о рекламе

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

Длительность рекламной паузы (в миллисекундах). Также называется длительностью рекламного блока.

Если используется EABN, значение pd должно совпадать с продолжительностью, указанной в уведомлении о рекламной паузе. Если продолжительность не совпадает, приоритет будет отдан значению EABN.

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

Настраиваемые параметры для таргетинга рекламных пауз, как описано в Справочном центре Ad Manager .

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

Сигнал SCTE-35, закодированный в base64.

Если сигнал недействителен, в HTTP-заголовке ответа будет отправлено сообщение X-Ad-Manager-Dai-Warning , и запрос будет отправлен без недействительного значения scte35.

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

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

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

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

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

Параметры
delta_token необязательный string

Непрозрачный токен, представляющий текущее состояние синхронизации клиента. Если он указан, сервер возвращает только метаданные, изменившиеся с момента генерации токена, а также новый next_delta_token в ответе. Если он опущен, сервер возвращает полные метаданные для всего окна DVR.

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

В случае успеха ответ возвращает экземпляр PodMetadata .

Анализ метаданных

Метаданные состоят из трех отдельных разделов: tags , ads и рекламные breaks . Точкой входа в данные является раздел tags . Оттуда нужно пройтись по тегам и найти первую запись, имя которой является префиксом идентификатора рекламного ролика, найденного в видеопотоке. Например, идентификатор рекламного ролика может выглядеть так:

google_1234567890

Затем вы находите объект тега с именем google_12345 . В данном случае он соответствует идентификатору вашего рекламного объявления. Как только вы найдете правильный объект префикса рекламного объявления, вы можете выполнить поиск идентификаторов объявлений, идентификаторов рекламных пауз и типа события. Идентификаторы объявлений затем используются для индексации объектов ads , а идентификаторы рекламных пауз — для индексации объектов breaks .

Объекты API

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

Объект 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. Заполняется для событий Livestream типа динамической вставки рекламы POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

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

PodMetadata

PodMetadata содержит метаданные о рекламе, рекламных паузах и идентификаторах медиафайлов.
JSON-представление
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Поля
tags map[string, object(TagSegment)]

Карта сегментов тегов, проиндексированных по префиксу тега.
ads map[string, object(Ad)]

Карта объявлений, проиндексированных по идентификатору объявления.
ad_breaks map[string, object(AdBreak)]

Карта рекламных пауз, отсортированных по идентификатору рекламной паузы.
next_delta_token string

Непрозрачный токен, который клиент сможет использовать в следующем опросе.
obsolete_ad_break_ids string

Список идентификаторов рекламных пауз, которые устарели и должны быть удалены из кэша клиента.

TagSegment

TagSegment содержит ссылку на объявление, его рекламный блок и тип события. TagSegment с типом "progress" не должен отправляться на конечную точку проверки рекламного контента.
JSON-представление
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Поля
ad string

Идентификатор объявления, к которому относится этот тег.
ad_break_id string

Идентификатор рекламного блока этого тега.
type string

Тип события этого тега.

AdBreak

AdBreak описывает одну рекламную паузу в потоке. Она содержит продолжительность, тип (в середине/перед/после) и количество рекламных объявлений.
JSON-представление
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Поля
type string

Допустимые типы перерывов: до, во время и после.
duration number

Общая продолжительность рекламного блока в секундах.
expected_duration number

Ожидаемая продолжительность рекламной паузы (в секундах), включая все рекламные объявления и любые заставки.
ads number

Количество рекламных объявлений в рекламной паузе.
Ad описывает рекламное объявление в ленте.
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)]

Список оберток (Wrappers), опускается, если список пуст.
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 — это длительность сегментов периода в миллисекундах.

AdpodTimingMetadataResponse

Объект AdpodTimingMetadataResponse содержит информацию о рекламном блоке и о том, как создавать для него URL-адреса сегментов.
JSON-представление
{
  "status": string,
  "ads": [object(AdRendering)],
  "slate": object(SlateRendering),
  "dash_representations": map[string, object(DASHRepresentation)],
  "dash_adaptation_sets": map[string, object(DASHAdaptationSet)],
}
Поля
status string

Статус решения по рекламному блоку.
ads [object(AdRendering)]

Массив объектов Ad, описывающих способ отображения URL-адресов сегментов рекламы, индексированный начиная с 0.
slate object(SlateRendering)

Описание Slate, демонстрирующее способ отображения URL-адресов сегментов Slate.
dash_representations map[string, object(DASHRepresentation)]

Список DASH-представлений для данного рекламного блока, которые должны отображаться в DASH-манифестах.
dash_adaptation_sets map[string, object(DASHAdaptationSet)]

Список наборов адаптаций DASH для данного рекламного блока, которые должны отображаться в манифестах DASH.

AdRendering

AdRendering описывает, как отобразить рекламное объявление, по которому было принято решение.
JSON-представление
{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}
Поля
duration_ms number

Длительность рекламного ролика в миллисекундах (целое число).
variants map[string, object(VariantRendering)]

Словарь объектов Variant (см. ниже), индексированный по идентификатору варианта/профиля, настроенному в пользовательском интерфейсе.

SlateRendering

SlateRendering описывает способ отображения контента в формате Slate.
JSON-представление
{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}
Поля
duration_ms number

Длительность отображения времени в миллисекундах (целые числа).
variants map[string, object(VariantRendering)]

Словарь объектов Variant, индексированных по идентификатору варианта/профиля. Длительность заставки должна повторяться до достижения требуемой длины, с вставкой разрывов HLS между итерациями или с повторением новых периодов для MPEG-DASH.

VariantRendering

VariantRendering описывает один вариант/профиль в рамках рекламной кампании/списка объявлений.
JSON-представление
{
  "segment_extension": string,
  "segment_durations": object(SegmentDurations),
}
Поля
segment_extension string

Строка, одна из следующих: ts, mp4, aac, ac3, ec3, m4a, m4v. Расширение имени файла, являющееся частью URL-адресов сегментов.
segment_durations object(SegmentDurations)

Объекты SegmentDurations. Продолжительность каждого сегмента может быть преобразована в URL-адрес сегмента.

SegmentDurations

Параметр SegmentDurations описывает длительность последовательности сегментов в заданной единице времени.
JSON-представление
{
  "timescale": number,
  "values": [],
}
Поля
timescale number

Временная шкала — это количество единиц в секунду (целое число). Ожидаемое значение: 1000 для HLS (миллисекунды), 90000 для видео DASH (PTS). Частота дискретизации звука для аудио DASH.
values number

Массив длительностей целочисленных сегментов в единицах временной шкалы.

Представительство DASH

DASHRepresentation описывает узлы представления, которые должны отображаться в манифестах DASH.
JSON-представление
{
  "codecs": string,
  "bandwidth": number,
  "width": number,
  "height": number,
  "frame_rate": string,
  "audio_sampling_rate": number,
  "audio_channel_config": object(SchemeIDURIAndValue),
}
Поля
codecs string

Кодеки представления.
bandwidth number

Пропускная способность представления.
width number

Ширина изображения.
height number

Высота изображения.
frame_rate string

Частота кадров представления.
audio_sampling_rate number

Частота дискретизации звука в представлении.
audio_channel_config object(SchemeIDURIAndValue)

Настройка аудиоканалов представления.

DASHAdaptationSet

DASHAdaptationSet описывает узлы AdaptationSet, которые должны отображаться в манифестах DASH.
JSON-представление
{
  "content_type": string,
  "mime_type": string,
  "role": object(SchemeIDURIAndValue),
  "inband_event_stream": object(SchemeIDURIAndValue),
  "min_frame_rate": string,
  "max_frame_rate": string,
  "scan_type": string,
  "start_with_sap": string,
  "segment_alignment": boolean,
  "representations": [],
}
Поля
content_type string

Тип контента адаптационного набора.
mime_type string

MIME-тип набора адаптаций.
role object(SchemeIDURIAndValue)

Роль адаптационного набора.
inband_event_stream object(SchemeIDURIAndValue)

Встроенный поток событий набора адаптации.
min_frame_rate string

Минимальная частота кадров в адаптационном наборе.
max_frame_rate string

Максимальная частота кадров в адаптационном наборе.
scan_type string

Тип сканирования адаптационного набора.
start_with_sap string

Начните с SAP из набора адаптационных модулей.
segment_alignment boolean

Выравнивание сегментов адаптационного набора.
representations string

Представление набора адаптаций.

Схема IDURIAndValue

SchemeIDURIAndValue — это пара, состоящая из идентификатора схемы и её значения.
JSON-представление
{
  "scheme_id_uri": string,
  "value": string,
}
Поля
scheme_id_uri string

URI идентификатора схемы значения.
value string

Значение URI идентификатора схемы.

Икона

Icon содержит информацию об иконке 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

Данные ClickData содержат информацию о клике по значку.
JSON-представление
{
  "url": string,
}
Поля
url string

FallbackImage

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

Упаковка

Wrapper содержит информацию о рекламном объявлении-оболочке. Он не включает идентификатор предложения (Deal ID), если он отсутствует.
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 ID.
creative_ad_id string

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

Необязательный идентификатор сделки для рекламного объявления-оболочки.

Проверка

В разделе «Верификация» содержится информация для Open Measurement, которая упрощает измерение видимости и верификацию сторонними сервисами. В настоящее время поддерживаются только ресурсы 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

Непрозрачная строка, передаваемая коду проверки начальной загрузки.

JavaScriptResource

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

Событие отслеживания, которое необходимо проверить с помощью команды ping.

UniversalAdID

UniversalAdID используется для предоставления уникального идентификатора рекламного креатива, который сохраняется во всех рекламных системах.
JSON-представление
{
  "id_value": string,
  "id_registry": string,
}
Поля
id_value string

Универсальный идентификатор объявления (Universal Ad ID) выбранного креатива для рекламы.
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.
,

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-под, обслуживающий сессию прямой трансляции.

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 Tech Lab и спецификацию 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}

Строковый идентификатор текущей рекламной паузы. Любой неизвестный идентификатор рекламной паузы, предоставленный этому адресу, создаст новую рекламную паузу для прямой трансляции.

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.
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

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • pod_id или ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp
last необязательный boolean

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

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

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

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

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

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

Сноски

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

Пример

GET 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

GET 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_identifier}.m3u8;

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

HTTP-запрос 

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

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

Параметры
network_code string

Код рекламной сети Google Ad Manager издателя.

custom_asset_key string

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

pod_identifier

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

pod/{integer}

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

ad_break_id/{string}

Строковый идентификатор текущей рекламной паузы. Любой неизвестный идентификатор рекламной паузы, предоставленный этому адресу, создаст новую рекламную паузу для прямой трансляции.

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.

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

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

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

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

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

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

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

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

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

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

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • pod_id или ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp

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

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

Метод: манифест DASH-пода

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

Методы
GET GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/{pod_identifier}/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_identifier

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

pod/{integer}

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

ad_break_id/{string}

Строковый идентификатор текущей рекламной паузы. Любой неизвестный идентификатор рекламной паузы, предоставленный этому адресу, создаст новую рекламную паузу для прямой трансляции.

К пользовательским идентификаторам рекламных блоков применяются следующие ограничения:

  • Длина должна составлять от 1 до 63 символов.
  • Должно содержать только строчные буквы, цифры и дефисы.

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

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

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

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

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

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

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

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

auth-token представляет собой закодированный HMAC-токен со следующими данными:

  • pod_id или ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp

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

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

Метод: Шаблон периода DASH-под

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

Запрашивает у Google Ad Manager шаблон периода DASH. Этот шаблон содержит макросы, которые необходимо заполнить параметрами вашего потока. После заполнения этих макросов шаблон становится периодом для вашей рекламной паузы и может быть интегрирован в ваш манифест 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 .

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

Версия шаблона. По умолчанию — 0 Указывает версию шаблона пода, которую необходимо вернуть.

  • 0 : Запрашивает шаблон, использующий идентификатор последовательности пода.
  • 1 : Запрашивает шаблон, поддерживающий как идентификаторы последовательности подов, так и идентификаторы рекламных пауз.

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

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

Метод: Метаданные о времени показа рекламного блока

Методы
ad pod timing metadata GET /linear/pods/v1/adv/network/{network_code}/custom_asset/{custom_asset_key}/pod.json

Получает метаданные о времени показа рекламных блоков.

HTTP-запрос 

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

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

Параметры
network_code string

Код рекламной сети Google Ad Manager издателя.

custom_asset_key string

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

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

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

Идентификатор потока Ad Manager из клиентского приложения видеоплеера.

ad_break_id необходимый string

Следующая заставка рекламной паузы.

Ad break IDs are provided by the Stitching server or VTP, and must match across early ad break notifications, ad pod timing metadata requests, and segment redirect requests for the same ad break.

The following restrictions apply to custom adbreak IDs:

  • Must be between 1 and 63 characters long
  • Must contain only lowercase letters, digits, and hyphens.
  • The ad break id preroll is reserved to retrieve the preroll ad pod. It cannot be used to identify any other ad pod.
auth-token необходимый string

The auth-token consists of an encoded HMAC token with the following data:

  • ad_break_id
  • network_code
  • custom_asset_key
  • cust_params
  • pd
  • scte35
  • exp
timeout необязательный integer

The number of milliseconds that DAI can block this request to wait for ad decisioning. Use this parameter on requests that must return populated ads on the first request, such as pre-roll ad breaks.

If timeout is exceeded, the request returns a status of pending.

If included, the timeout value must be between 1000 and 15000 milliseconds. If omitted, responses are not delayed to wait for ad decisioning.

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

Set to true to indicate to DAI that this is the last request the VTP is willing to make for this ad pod. If an ad decision isn't available yet (by the optional timeout), DAI will return slate permanently for this request.

Defaults to false .

Ad decisioning parameters

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

The duration of the ad break (in milliseconds). Also referred to as ad pod duration.

If EABN is used, the pd value must match the duration provided in your ad break notification. If the durations don't match, the EABN value will be given priority.

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

Custom parameters for ad break targeting, as described in the Ad Manager Help Center .

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

A base64-encoded SCTE-35 signal.

If the signal is invalid, a message will be sent in the X-Ad-Manager-Dai-Warning HTTP header of the response and the request will be sent without the invalid scte35 value.

Response body

If successful, the response body contains a new AdPodTimingMetadataResponse object.

Method: media verification

After encountering an ad media identifier during playback, immediately make a request using the media_verification_url obtained from the stream endpoint, above. These requests aren't necessary for server-side-beaconing streams, where the server initiates media verification.

Requests to the media verification endpoint are idempotent.

Методы
media verification GET /{media_verification_url}/{ad_media_id}

Notifies the API of a media verification event.

HTTP-запрос 

GET https://{media-verification-url}/{ad-media-id}

Response body

media verification returns the following responses:

  • HTTP/1.1 204 No Content if media verification succeeds and all pings are sent.
  • HTTP/1.1 404 Not Found if the request can't verify the media due to incorrect URL formatting or expiration.
  • HTTP/1.1 404 Not Found if a previous verification request for this ID succeeded.
  • HTTP/1.1 409 Conflict if another request is already sending pings at this time.

Ad media IDs

Ad media identifiers will be encoded in a separate metadata track — timed metadata for HLS transport stream, or emsg for mp4 files. Ad media identifiers will always begin with the string google_ .

The entire text contents of the metadata entry should be appended to the ad verification URL prior to making each ad verification request.

Method: metadata

The metadata endpoint at metadata_url returns information used to build an ad UI. The metadata endpoint isn't available for server-side-beaconing streams, where the server is responsible for initiating ad media verification.

Методы
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Retrieves ad metadata information.

HTTP-запрос 

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

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

Параметры
delta_token необязательный string

An opaque token representing the client's current synchronization state. If provided, the server returns only the metadata that has changed since the token was generated, along with a new next_delta_token in the response. If omitted, the server returns the full metadata for the entire DVR window.

Response body

If successful, the response returns an instance of PodMetadata .

Parsing Metadata

Metadata has three discrete sections: tags , ads , and ad breaks . The entry point into the data is the tags section. From there, iterate through the tags and find the first entry whose name is a prefix for the ad media ID found in the video stream. For example, you might have an ad media ID that looks like:

google_1234567890

Then you find a tag object named google_12345 . In this case, it matches your ad media id. Once you find the correct ad media prefix object, you can look up ad ids, ad break ids, and the event type. Ad ids are then used to index the ads objects and ad break ids are used to index the breaks objects.

API Objects

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

Stream is used to render a list of resources for a newly created stream in JSON format.
JSON representation
{
  "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

The GAM stream identifier.
media_verification_url string

The media verification URL used as base endpoint for tracking playback events.
metadata_url string

Metadata URL used to poll for periodic information about upcoming stream ad events.
session_update_url string

The session's update URL used to update the targeting parameters for this stream. The original values for the targeting parameters are captured during the initial stream create request.
heartbeat_url string

The heartbeat URL, used to keep the server side beaconing stream alive, it must be pinged every {PollingFrequency} seconds. Populated for server side beaconing streams.
polling_frequency number

The polling frequency, in seconds, when requesting metadata_url or heartbeat_url.
pod_manifest_url string

The pod manifest URL template is used to generate the URL to retrieve a stream's pod manifest, corresponding to the URL of the multivariant playlist in HLS or the MPD in DASH. Populated for Livestream events of Dynamic Ad Insertion type POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Manifest format is the format of the manifest retrieved from pod_manifest_url, either dash or hls.

PodMetadata

PodMetadata contains metadata information on ads, ad breaks, and media ID tags.
JSON representation
{
  "tags": map[string, object(TagSegment)],
  "ads": map[string, object(Ad)],
  "ad_breaks": map[string, object(AdBreak)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Поля
tags map[string, object(TagSegment)]

Map of tag segments indexed by tag prefix.
ads map[string, object(Ad)]

Map of ads indexed by ad ID.
ad_breaks map[string, object(AdBreak)]

Map of ad breaks indexed by ad break ID.
next_delta_token string

An opaque token for the client to use on the next poll.
obsolete_ad_break_ids string

A list of ad break IDs that are obsolete and should be removed from the client's cache.

TagSegment

TagSegment contains a reference to an ad, its ad break, and event type. TagSegment with type="progress" should not be pinged to the ad media verification endpoint.
JSON representation
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Поля
ad string

The ID of this tag's ad.
ad_break_id string

The ID of this tag's ad break.
type string

This tag's event type.

AdBreak

AdBreak describes a single ad break in the stream. It contains a duration, a type (mid/pre/post) and the number of ads.
JSON representation
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Поля
type string

Valid break types are: pre, mid, and post.
duration number

Total ad duration for this ad break, in seconds.
expected_duration number

Expected duration of the ad break (in seconds), including all ads and any slate.
ads number

Number of ads in the ad break.
Ad describes an ad in the stream.
JSON representation
{
  "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

The ID of this ad's ad break.
position number

Position of this ad in the ad break, starting at 1.
duration number

Duration of the ad, in seconds.
title string

Optional title of the ad.
description string

Optional description of the ad.
advertiser string

Optional advertiser identifier.
ad_system string

Optional ad system.
ad_id string

Optional ad ID.
creative_id string

Optional creative ID.
creative_ad_id string

Optional creative ad ID.
deal_id string

Optional deal ID.
clickthrough_url string

Optional clickthrough URL.
click_tracking_urls string

Optional click tracking URLs.
verifications [object(Verification)]

Optional Open Measurement verification entries which list the resources and metadata required to execute third-party measurement code to verify creative playback.
slate boolean

Optional bool indicating the current entry is slate.
icons [object(Icon)]

A list of icons, omitted if empty.
wrappers [object(Wrapper)]

A list of Wrappers, omitted if empty.
universal_ad_id object(UniversalAdID)

Optional universal ad ID.
extensions string

Optional list of all <Extension> nodes in the VAST.
companions [object(Companion)]

Optional companions that may be displayed along with this ad.
interactive_file object(InteractiveFile)

Optional interactive creative (SIMID) that should be displayed during ad playback.

PodTemplateResponse

PodTemplateResponse represents the JSON payload returned to a VTP for pod stitching.
JSON representation
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Поля
dash_period_template string

DashPeriodTemplate is the xml template for the period to be filled with appropriate data before stitching.
segment_duration_ms int64

SegmentDurationMS is the duration of the period segments in milliseconds.

AdpodTimingMetadataResponse

AdpodTimingMetadataResponse contains information about the Ad Pod and how to build segment URLs for it.
JSON representation
{
  "status": string,
  "ads": [object(AdRendering)],
  "slate": object(SlateRendering),
  "dash_representations": map[string, object(DASHRepresentation)],
  "dash_adaptation_sets": map[string, object(DASHAdaptationSet)],
}
Поля
status string

Decision status for the ad pod.
ads [object(AdRendering)]

Array of Ad objects describing how to render the ad segment urls, indexed starting at 0.
slate object(SlateRendering)

Slate describing how to render the slate segment urls.
dash_representations map[string, object(DASHRepresentation)]

List of DASH Representations for that ad pod to be rendered in DASH manifests.
dash_adaptation_sets map[string, object(DASHAdaptationSet)]

List of DASH Adaptation Sets for that ad pod to be rendered in DASH manifests.

AdRendering

AdRendering describes how to render a decisioned ad.
JSON representation
{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}
Поля
duration_ms number

Duration of the ad, in milliseconds (int).
variants map[string, object(VariantRendering)]

Dictionary of Variant objects (see below), indexed by the variant/profile ID, as configured from the UI.

SlateRendering

SlateRendering describes how to render slate content.
JSON representation
{
  "duration_ms": number,
  "variants": map[string, object(VariantRendering)],
}
Поля
duration_ms number

Duration of the slate, in milliseconds (int).
variants map[string, object(VariantRendering)]

Dictionary of Variant objects, indexed by variant/profile ID. Slate durations must be looped until the required slate length is reached, inserting HLS discontinuities between iterations, or looping new periods for MPEG-DASH.

VariantRendering

VariantRendering describes one variant/profile within the ad/slate.
JSON representation
{
  "segment_extension": string,
  "segment_durations": object(SegmentDurations),
}
Поля
segment_extension string

String, one of: ts, mp4, aac, ac3, ec3, m4a, m4v. Filename extension part of the segment URLs.
segment_durations object(SegmentDurations)

SegmentDurations objects. Each segment duration can be translated into a segment URL.

SegmentDurations

SegmentDurations describes the duration of a sequence of segments, in a specified time unit.
JSON representation
{
  "timescale": number,
  "values": [],
}
Поля
timescale number

Timescale is the number of units per second (int) Expected to be: 1000 for HLS (milliseconds) 90000 for DASH video (PTS) Audio sample rate for DASH audio.
values number

Array of int segment durations, in timescale units.

DASHRepresentation

DASHRepresentation describes Representation nodes to be rendered in DASH manifests.
JSON representation
{
  "codecs": string,
  "bandwidth": number,
  "width": number,
  "height": number,
  "frame_rate": string,
  "audio_sampling_rate": number,
  "audio_channel_config": object(SchemeIDURIAndValue),
}
Поля
codecs string

Codecs of the representation.
bandwidth number

Bandwidth of the representation.
width number

Width of the representation.
height number

Height of the representation.
frame_rate string

Frame rate of the representation.
audio_sampling_rate number

Audio sampling rate of the representation.
audio_channel_config object(SchemeIDURIAndValue)

Audio channel configuration of the representation.

DASHAdaptationSet

DASHAdaptationSet describes AdaptationSet nodes to be rendered in DASH manifests.
JSON representation
{
  "content_type": string,
  "mime_type": string,
  "role": object(SchemeIDURIAndValue),
  "inband_event_stream": object(SchemeIDURIAndValue),
  "min_frame_rate": string,
  "max_frame_rate": string,
  "scan_type": string,
  "start_with_sap": string,
  "segment_alignment": boolean,
  "representations": [],
}
Поля
content_type string

Content type of the adaptation set.
mime_type string

MIME type of the adaptation set.
role object(SchemeIDURIAndValue)

Role of the adaptation set.
inband_event_stream object(SchemeIDURIAndValue)

Inband event stream of the adaptation set.
min_frame_rate string

Minimum frame rate of the adaptation set.
max_frame_rate string

Maximum frame rate of the adaptation set.
scan_type string

Scan type of the adaptation set.
start_with_sap string

Start with SAP of the adaptation set.
segment_alignment boolean

Segment alignment of the adaptation set.
representations string

Representations of the adaptation set.

SchemeIDURIAndValue

SchemeIDURIAndValue is a pair of a scheme ID and its value.
JSON representation
{
  "scheme_id_uri": string,
  "value": string,
}
Поля
scheme_id_uri string

Scheme ID URI of the value.
value string

Value of the scheme ID URI.

Икона

Icon contains information about a VAST Icon.
JSON representation
{
  "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

ClickData contains information about an icon clickthrough.
JSON representation
{
  "url": string,
}
Поля
url string

FallbackImage

FallbackImage contains information about a VAST fallback image.
JSON representation
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Поля
creative_type string

height int32

width int32

resource string

alt_text string

Упаковка

Wrapper contains information about a wrapper ad. It does not include a Deal ID if it does not exist.
JSON representation
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Поля
system string

Ad system identifier.
ad_id string

Ad ID used for the wrapper ad.
creative_id string

Creative ID used for the wrapper ad.
creative_ad_id string

Creative Ad ID used for the wrapper ad.
deal_id string

Optional deal ID for the wrapper ad.

Проверка

Verification contains information for Open Measurement, which facilitates third-party viewability and verification measurement. Currently, only JavaScript resources are supported. See https://iabtechlab.com/standards/open-measurement-sdk/
JSON representation
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Поля
vendor string

The verification vendor.
java_script_resources [object(JavaScriptResource)]

List of JavaScript resources for the verification.
tracking_events [object(TrackingEvent)]

List of tracking events for the verification.
parameters string

An opaque string passed to bootstrap verification code.

JavaScriptResource

JavaScriptResource contains information for verification via JavaScript.
JSON representation
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Поля
script_url string

URI to javascript payload.
api_framework string

APIFramework is the name of the video framework exercising the verification code.
browser_optional boolean

Whether this script can be run outside of a browser.

TrackingEvent

TrackingEvent contains URLs that should be pinged by the client in certain situations.
JSON representation
{
  "event": string,
  "uri": string,
}
Поля
event string

The type of the tracking event.
uri string

The tracking event to be pinged.

UniversalAdID

UniversalAdID is used to provide a unique creative identifier that is maintained across ad systems.
JSON representation
{
  "id_value": string,
  "id_registry": string,
}
Поля
id_value string

The Universal Ad ID of the selected creative for the ad.
id_registry string

A string used to identify the URL for the registry website where the selected creative's Universal Ad ID is cataloged.

Спутник

Companion contains information for companion ads that may be displayed along with ad.
JSON representation
{
  "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)

The click data for this companion.
creative_type string

The CreativeType attribute on the <StaticResource> node in the VAST if this is a companion of type static.
height int32

The height in pixels of this companion.
width int32

The width in pixels of this companion.
resource string

For static and iframe companions this will be the URL to be loaded and displayed. For HTML companions, this will be the HTML snippet that should be shown as the companion.
type string

Type of this companion. It can be either static, iframe or HTML.
ad_slot_id string

The slot ID for this companion.
api_framework string

The API framework for this companion.
tracking_events [object(TrackingEvent)]

List of tracking events for this companion.

InteractiveFile

InteractiveFile contains information for interactive creative (ie SIMID) that should be displayed during ad playback.
JSON representation
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Поля
resource string

The URL to the interactive creative.
type string

The MIME type of the file provided as the resource.
variable_duration boolean

Whether this creative may ask for the duration to be extended.
ad_parameters string

The value of the <AdParameters> node in the VAST.