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/{pod_id}/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/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}
Параметры пути
Параметры | |
---|---|
network_code | string Сетевой код Google Ad Manager издателя. |
custom_asset_key | string Пользовательский идентификатор, связанный с этим событием в Google Ad Manager. |
pod_id | integer Числовой идентификатор текущей рекламной паузы. Идентификаторы рекламных модулей назначаются постепенно для каждого события, начиная с 1. |
profile_name | string Название запрошенного профиля кодирования DAI Google Ad Manager . Профиль кодирования должен быть одним из настроенных профилей кодирования для выбранного события. |
segment_number | integer Индекс запрошенного сегмента в текущем рекламном пакете, начиная с нуля. |
segment_format | string Расширение файла, связанное с запрошенным форматом сегмента. Принимаемые расширения: |
Параметры запроса
Параметры | ||||||
---|---|---|---|---|---|---|
stream_id | необходимый | string Идентификатор потока для сеанса текущего пользователя. Это значение возвращается в результате успешного запроса к конечной точке | ||||
sd | required 1 | integer Длительность запрошенного сегмента в миллисекундах. | ||||
so | необязательный | Смещение запрошенного сегмента внутри рекламного модуля в миллисекундах. Если вы опустите параметр | ||||
pd | требуется 2 | integer Продолжительность рекламного блока в миллисекундах. | ||||
auth-token | необходимый | string Подписанный токен HMAC в кодировке URL для текущего рекламного модуля. | ||||
last | необязательный | boolean Указывает последний сегмент рекламной паузы. Опустите этот параметр для всех остальных сегментов. | ||||
scte35 | необязательный | string Сигнал SCTE-35 в кодировке Base64 для этой рекламной паузы. | ||||
cust_params | необязательный | string Набор пар ключ-значение, используемый для таргетинга кампании Менеджера рекламы. Эти пары должны быть представлены в виде строки запроса в кодировке URL. Пример:
|
Сноски
-
sd
не требуется для сегментов инициализации. ↩ -
pd
не требуется для мероприятий с включенными бесконечными рекламными паузами. ↩
Тело ответа
В случае успеха телом ответа будет воспроизводимый сегмент потока, соответствующий формату и параметрам, указанным в запросе.
Метод: шаблон периода модуля 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 Идентификатор потока для сеанса текущего пользователя. Это значение возвращается в результате успешного запроса к конечной точке |
Тело ответа
В случае успеха тело ответа содержит новый объект 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. |