API lineal de inserción de anuncios dinámicos

La API de inserción de anuncios dinámicos te permite solicitar y realizar un seguimiento de las transmisiones lineales de DAI (EN VIVO).

Servicio: dai.google.com

Todos los URI que aparecen a continuación están relacionados con https://dai.google.com

Método: stream

Métodos
stream	POST /linear/v1/hls/event/{assetKey}/stream Crea una transmisión de DAI para el ID del evento determinado.

Solicitud HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

Encabezado de la solicitud

Parámetros
api‑key	string La clave de API, que se proporciona cuando se crea una transmisión, debe ser válida para la red del publicador. En lugar de proporcionarla en el cuerpo de la solicitud, la clave de API se puede pasar en el encabezado de autorización HTTP con el siguiente formato: Authorization: DCLKDAI key="<api-key>"

Parámetros de ruta de acceso

Parámetros
assetKey	string El ID del evento de la transmisión. Nota: La clave del activo de transmisión es un identificador que también se puede encontrar en la IU de Ad Manager.

Cuerpo de la solicitud

El cuerpo de la solicitud es de tipo application/x-www-form-urlencoded y contiene los siguientes parámetros:

Parámetros
dai-ssb	Opcional	Configúralo en true para crear una transmisión de balizas del servidor. La configuración predeterminada es false. El cliente inicia el seguimiento de la transmisión predeterminada y se hace ping desde el servidor.
Parámetros de segmentación de DFP	Opcional	Parámetros de segmentación adicionales.
Anular parámetros de transmisión	Opcional	Anula los valores predeterminados de un parámetro de creación de transmisión.
Autenticación HMAC	Opcional	Autentícate con un token basado en HMAC.

Cuerpo de la respuesta

Si se ejecuta de forma correcta, el cuerpo de la respuesta contiene un Stream nuevo. En el caso de las transmisiones de balizas del servidor, este Stream solo contiene los campos stream_id y stream_manifest.

Open Measurement

La API de DAI contiene información para la verificación de Open Measurement en el campo Verifications. Este campo contiene uno o más elementos Verification que enumeran los recursos y metadatos necesarios para ejecutar un código de medición de terceros a fin de verificar la reproducción de creatividades. Solo se admite JavaScriptResource. Para obtener más información, consulta IAB Tech Lab y las especificaciones de VAST 4.1.

Método: verificación de contenido multimedia

Después de encontrar un identificador de medios de anuncios durante la reproducción, realiza una solicitud de inmediato mediante la media_verification_url que se obtuvo del extremo stream, anterior. Estas solicitudes no son necesarias para las transmisiones de balizas del servidor, en las que el servidor inicia la verificación de medios.

Las solicitudes al extremo media verification son idempotentes.

Métodos
media verification	GET /{media_verification_url}/{ad_media_id} Notifica a la API sobre un evento de verificación de medios.

Nota: No se debe hacer ping a los eventos Progress ID3 a este extremo. Sirven para que los publicadores diferencien la reproducción dentro y fuera de una pausa publicitaria, y no sirven para otros fines de seguimiento de anuncios. Los publicadores pueden identificar eventos de progreso buscando el identificador de contenido multimedia en el archivo JSON de metadatos y verificando que el campo type esté configurado como progress.

Solicitud HTTP

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

Cuerpo de la respuesta

media verification muestra las siguientes respuestas:

• Es HTTP/1.1 204 No Content si la verificación de medios se realiza correctamente y se envían todos los pings.
• Se utiliza HTTP/1.1 404 Not Found si la solicitud no puede verificar el contenido multimedia debido a un vencimiento o formato de URL incorrectos.
• HTTP/1.1 404 Not Found si se realiza correctamente una solicitud de verificación anterior para este ID.
• Es HTTP/1.1 409 Conflict si otra solicitud ya está enviando pings en este momento.

IDs de medios de anuncios (HLS)

Los identificadores multimedia de anuncios se codificarán en metadatos temporizados de HLS con la clave TXXX, reservada para los marcos de “información de texto definida por el usuario”. El contenido del marco no se encriptará y siempre comenzará con el texto "google_".

Todo el contenido del texto del marco se debe agregar a la URL de verificación de anuncios antes de realizar cada solicitud de verificación de anuncios.

Método: metadata

El extremo de metadatos en metadata_url muestra información que se usa para compilar una IU de anuncios. El extremo de metadatos no está disponible para las transmisiones de balizas del servidor, en las que el servidor es responsable de iniciar la verificación de medios del anuncio.

Métodos
metadata	GET /{metadata_url}/{ad-media-id} GET /{metadata_url} Recupera información de los metadatos de los anuncios.

Nota: Se recomienda que proporciones el ID de medios del anuncio en el extremo. De lo contrario, usa polling_frequency para determinar la frecuencia con la que te conectarás a este extremo.

Solicitud HTTP

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

GET https://{metadata_url}

Cuerpo de la respuesta

Si se ejecuta de forma correcta, la respuesta muestra una instancia de PodMetadata.

Trabaja con metadatos

Los metadatos tienen tres secciones discretas: tags, ads y el anuncio breaks. El punto de entrada a los datos es la sección tags. Desde allí, itera las etiquetas y busca la primera entrada cuyo nombre sea un prefijo para el ID de contenido multimedia del anuncio que se encuentra en la transmisión de video por Internet. Por ejemplo, es posible que tengas un ID de medios de anuncio que se ve de la siguiente manera:

google_1234567890

Luego, encuentras un objeto de etiqueta llamado google_12345. En este caso, coincide con el ID de contenido multimedia de tu anuncio. Una vez que hayas encontrado el objeto del prefijo de contenido multimedia del anuncio correcto, puedes buscar los IDs de los anuncios, los IDs de las pausas publicitarias y el tipo de evento. Luego, los IDs de anuncios se usan para indexar los objetos ads y los IDs de pausas publicitarias se usan para indexar los objetos breaks.

Datos de respuesta

Transmisión

La transmisión se usa para renderizar una lista de recursos de una transmisión recién creada en formato JSON.

Representación JSON
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, }

Campos
stream_id	string El identificador de transmisión de GAM.
stream_manifest	string La URL del manifiesto de la transmisión, que se usa para recuperar la playlist de múltiples variantes en HLS o en MPD en DASH.
hls_master_playlist	string (OBSOLETO) URL de playlist de múltiples variantes de HLS. En su lugar, usa "stream_manifest".
media_verification_url	string La URL de verificación de contenido multimedia que se usa como extremo base para hacer un seguimiento de los eventos de reproducción
metadata_url	string URL de metadatos que se usa para consultar información periódica sobre los próximos eventos de anuncios de transmisión.
session_update_url	string Es la URL de actualización de la sesión que se usa para actualizar los parámetros de segmentación de esta transmisión. Los valores originales de los parámetros de segmentación se capturan durante la solicitud inicial de creación de transmisión.
polling_frequency	number La frecuencia de sondeo, en segundos, cuando se solicita metadata_url desde o Heartbeat_url.

PodMetadata

PodMetadata contiene información de metadatos sobre anuncios, pausas publicitarias y etiquetas de ID de medios.

Representación JSON
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], }

Campos
tags	map[string, object(TagSegment)] Mapa de segmentos de etiquetas indexados por prefijo de etiqueta.
ads	map[string, object(Ad)] Mapa de anuncios indexados por ID de anuncio
ad_breaks	map[string, object(AdBreak)] Mapa de pausas publicitarias indexadas por ID de pausa publicitaria.

TagSegment

TagSegment contiene una referencia a un anuncio, su pausa publicitaria y el tipo de evento. No se debe hacer ping a TagSegment con type="progress" al extremo de verificación de medios del anuncio.

Representación JSON
{ "ad": string, "ad_break_id": string, "type": string, }

Campos
ad	string El ID del anuncio de esta etiqueta.
ad_break_id	string El ID de la pausa publicitaria de esta etiqueta
type	string Tipo de evento de esta etiqueta.

AdBreak

La pausa publicitaria describe una sola pausa publicitaria en la transmisión. Contiene una duración, un tipo (medio/previo/posterior) y la cantidad de anuncios.

Representación JSON
{ "type": string, "duration": number, "expected_duration": number, "ads": number, }

Campos
type	string Los tipos de pausa válidos son los siguientes: antes, durante y después.
duration	number Duración total del anuncio para esta pausa publicitaria, en segundos.
expected_duration	number Duración esperada de la pausa publicitaria (en segundos), incluidos todos los anuncios y cualquier cortinilla de video.
ads	number Cantidad de anuncios en la pausa publicitaria.

Anuncio

Un anuncio describe un anuncio en la transmisión.

Representación 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), }

Campos
ad_break_id	string El ID de la pausa publicitaria de este anuncio.
position	number Posición de este anuncio en la pausa publicitaria, a partir de 1.
duration	number Duración del anuncio, en segundos.
title	string Título opcional del anuncio.
description	string Descripción opcional del anuncio.
advertiser	string Identificador de anunciante opcional.
ad_system	string Sistema de anuncios opcional.
ad_id	string ID del anuncio opcional.
creative_id	string ID de la creatividad opcional.
creative_ad_id	string ID del anuncio con creatividad opcional
deal_id	string ID del acuerdo opcional.
clickthrough_url	string URL de clic opcional.
click_tracking_urls	string URLs de seguimiento de clics opcionales.
verifications	[object(Verification)] Entradas opcionales de verificación de Open Measurement que enumeran los recursos y metadatos necesarios para ejecutar un código de medición de terceros para verificar la reproducción de creatividades.
slate	boolean Bool opcional que indica que la entrada actual es de cortinilla de video.
icons	[object(Icon)] Una lista de íconos que se omite si está vacía.
wrappers	[object(Wrapper)] Una lista de wrappers, que se omite si está vacía.
universal_ad_id	object(UniversalAdID) ID del anuncio universal opcional.
extensions	string Lista opcional de todos los nodos de <Extension> de VAST.
companions	[object(Companion)] Anuncios complementarios opcionales que se pueden mostrar junto con este anuncio.
interactive_file	object(InteractiveFile) Creatividad interactiva opcional (SIMID) que se debe mostrar durante la reproducción del anuncio

Ícono

El ícono contiene información sobre un ícono de VAST.

Representación 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, }

Campos
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 contiene información sobre el clic de un ícono.

Representación JSON
{ "url": string, }

Campos
url	string

FallbackImage

FallbackImage contiene información sobre una imagen de resguardo de VAST.

Representación JSON
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, }

Campos
creative_type	string
height	int32
width	int32
resource	string
alt_text	string

Wrapper

El wrapper contiene información sobre un anuncio wrapper. No incluye un ID del acuerdo si no existe.

Representación JSON
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, }

Campos
system	string Identificador del sistema de anuncios.
ad_id	string ID del anuncio utilizado para el anuncio envolvente.
creative_id	string ID de la creatividad que se usa para el anuncio envolvente.
creative_ad_id	string ID de la creatividad que se usa para el anuncio envolvente.
deal_id	string ID de acuerdo opcional para el anuncio wrapper.

Verificación

La verificación contiene información de Open Measurement, que facilita la medición de visibilidad y verificación de terceros. Actualmente, solo se admiten recursos de JavaScript. Consulta https://iabtechlab.com/standards/open-measurement-sdk/

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

Campos
vendor	string El proveedor de verificación
java_script_resources	[object(JavaScriptResource)] Lista de recursos de JavaScript para la verificación.
tracking_events	[object(TrackingEvent)] Lista de eventos de seguimiento para la verificación.
parameters	string Una cadena opaca que se pasa al código de verificación de arranque.

JavaScriptResource

JavaScriptResource contiene información para la verificación mediante JavaScript.

Representación JSON
{ "script_url": string, "api_framework": string, "browser_optional": boolean, }

Campos
script_url	string El URI a la carga útil de JavaScript.
api_framework	string APIFramework es el nombre del framework del video que ejecuta el código de verificación.
browser_optional	boolean Indica si esta secuencia de comandos se puede ejecutar fuera de un navegador.

TrackingEvent

TrackingEvent contiene URLs a las que el cliente debe hacer ping en determinadas situaciones.

Representación JSON
{ "event": string, "uri": string, }

Campos
event	string El tipo de evento de seguimiento.
uri	string El evento de seguimiento al que se debe hacer ping

UniversalAdID

UniversalAdID se usa para proporcionar un identificador de creatividad único que se mantiene en todos los sistemas de anuncios.

Representación JSON
{ "id_value": string, "id_registry": string, }

Campos
id_value	string El ID del anuncio universal de la creatividad seleccionada para el anuncio.
id_registry	string Es una cadena que se usa para identificar la URL del sitio web de registro en el que se cataloga el ID del anuncio universal de la creatividad seleccionada.

Anuncio complementario

El anuncio complementario contiene información de los anuncios complementarios que se pueden mostrar junto con el anuncio.

Representación 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)], }

Campos
click_data	object(ClickData) Los datos de clics de este anuncio complementario.
creative_type	string Es el atributo CreativeType en el nodo <StaticResource> de VAST si es un anuncio complementario de tipo estático.
height	int32 Es la altura en píxeles de este anuncio complementario.
width	int32 Es el ancho en píxeles de este anuncio complementario.
resource	string En el caso de los elementos complementarios iframe y estáticos, esta será la URL que se cargará y mostrará. Para los anuncios complementarios HTML, este será el fragmento HTML que se debe mostrar como complementario.
type	string Tipo de este anuncio complementario. Puede ser estático, iframe o HTML.
ad_slot_id	string El ID del espacio de este anuncio complementario.
api_framework	string El framework de API de este complemento.
tracking_events	[object(TrackingEvent)] Lista de eventos de seguimiento de este anuncio complementario.

InteractiveFile

InteractiveFile contiene información para creatividades interactivas (es decir, SIMID) que se deben mostrar durante la reproducción de anuncios.

Representación JSON
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, }

Campos
resource	string La URL de la creatividad interactiva
type	string Es el tipo de MIME del archivo proporcionado como recurso.
variable_duration	boolean Determina si esta creatividad puede solicitar que se extienda la duración.
ad_parameters	string Es el valor del nodo <AdParameters> en VAST.