API lineal de inserción de anuncios dinámicos

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

Servicio: dai.google.com

Todos los URI son relativos a 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 de 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

Parámetros
assetKey string

Es el ID del evento de la transmisión.
Nota: La clave del recurso de transmisión también es un identificador que 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

Establécelo en true para crear una transmisión de balizas del servidor. La configuración predeterminada es false. El seguimiento del flujo predeterminado se inicia en el cliente y se hace ping en el servidor.
Parámetros de segmentación de DFP Opcional Son parámetros de segmentación adicionales.
Anular los parámetros de transmisión Opcional Anula los valores predeterminados de un parámetro de creación de transmisiones.
Autenticación con HMAC Opcional Autentica con un token basado en HMAC.

Cuerpo de la respuesta

Si el proceso se realiza correctamente, el cuerpo de la respuesta contiene un nuevo Stream. Para las transmisiones con 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 los metadatos necesarios para ejecutar el código de medición de terceros y verificar la reproducción de la creatividad. Solo se admite JavaScriptResource. Para obtener más información, consulta el IAB Tech Lab y la especificación de VAST 4.1.

Método: Verificación de medios

Después de encontrar un identificador de medios del anuncio durante la reproducción, realiza de inmediato una solicitud con la media_verification_url obtenida del extremo stream. 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.

Solicitud HTTP

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

Cuerpo de la respuesta

media verification devuelve las siguientes respuestas:

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

IDs de medios de anuncios (HLS)

Los identificadores de medios de los anuncios se codificarán en los metadatos cronometrados de HLS con la clave TXXX, reservada para los fotogramas de "información de texto definida por el usuario". El contenido del fotograma no estará encriptado y siempre comenzará con el texto "google_".

Todo el contenido de texto del fotograma 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 devuelve 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 publicitarios.

Métodos
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Recupera información de metadatos del anuncio.

Solicitud HTTP

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

GET https://{metadata_url}

Parámetros de consulta

Parámetros
delta_token opcional string

Es un token opaco que representa el estado de sincronización actual del cliente. Si se proporciona, el servidor solo devuelve los metadatos que cambiaron desde que se generó el token, junto con un nuevo next_delta_token en la respuesta. Si se omite, el servidor devuelve los metadatos completos de toda la ventana del DVR.

Cuerpo de la respuesta

Si se ejecuta correctamente, la respuesta devuelve una instancia de PodMetadata.

Trabaja con metadatos

Los metadatos tienen tres secciones discretas: tags, ads y breaks. El punto de entrada a los datos es la sección tags. A partir de ahí, itera por las etiquetas y busca la primera entrada cuyo nombre sea un prefijo para el ID de medios del anuncio que se encuentra en la transmisión de video. Por ejemplo, podrías tener un ID de medios del anuncio que se vea de la siguiente manera:

google_1234567890

Luego, encontrarás un objeto de etiqueta llamado google_12345. En este caso, coincide con el ID de medios de tu anuncio. Una vez que encuentres el objeto de prefijo de medios del anuncio correcto, podrás buscar los IDs de anuncios, los IDs de 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

Stream se usa para renderizar una lista de recursos para una transmisión creada recientemente 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

Es el identificador del flujo de GAM.
stream_manifest string

Es la URL del manifiesto de la transmisión, que se usa para recuperar la playlist de múltiples variantes en HLS o el MPD en DASH.
hls_master_playlist string

(EN DESUSO) URL de la playlist de múltiples variantes de HLS. En su lugar, usa "stream_manifest".
media_verification_url string

Es la URL de verificación de medios que se usa como endpoint base para hacer un seguimiento de los eventos de reproducción.
metadata_url string

URL de metadatos que se usa para sondear información periódica sobre los próximos eventos de anuncios en el flujo.
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 la transmisión.
polling_frequency number

Es la frecuencia de sondeo, en segundos, cuando se solicita metadata_url 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)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
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 las pausas publicitarias indexadas por ID de pausa publicitaria.
next_delta_token string

Es un token opaco que el cliente puede usar en la próxima votación.
obsolete_ad_break_ids string

Es una lista de IDs de pausas publicitarias que están obsoletos y se deben quitar de la caché del cliente.

TagSegment

TagSegment contiene una referencia a un anuncio, su pausa publicitaria y el tipo de evento. No se debe enviar un ping de 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

ID del anuncio de esta etiqueta.
ad_break_id string

ID de la pausa publicitaria de esta etiqueta.
type string

Es el tipo de evento de esta etiqueta.

AdBreak

AdBreak describe una sola pausa publicitaria en la transmisión. Contiene una duración, un tipo (intermedio, previo o posterior) y la cantidad de anuncios.
Representación JSON
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Campos
type string

Los tipos de interrupción válidos son pre, mid y post.
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 las cortinillas de video.
ads number

Cantidad de anuncios en la pausa publicitaria.
El 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

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 del anunciante opcional.
ad_system string

Sistema de anuncios opcional.
ad_id string

ID de anuncio opcional.
creative_id string

ID de creatividad opcional.
creative_ad_id string

ID de anuncio de la 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 de verificación de Open Measurement opcionales que enumeran los recursos y los metadatos necesarios para ejecutar el código de medición de terceros y verificar la reproducción de creatividades.
slate boolean

Es un valor booleano opcional que indica que la entrada actual es una pizarra.
icons [object(Icon)]

Una lista de íconos, que se omite si está vacía.
wrappers [object(Wrapper)]

Lista de Wrappers, se omite si está vacía.
universal_ad_id object(UniversalAdID)

ID de anuncio universal opcional.
extensions string

Lista opcional de todos los nodos <Extension> en 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 redireccionamiento de un ícono.
Representación JSON
{
  "url": string,
}
Campos
url string

FallbackImage

FallbackImage contiene información sobre una imagen de respaldo 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 de 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 que se usa para el anuncio de wrapper.
creative_id string

ID de la creatividad que se usa para el anuncio de envoltorio.
creative_ad_id string

ID del anuncio de la creatividad que se usa para el anuncio del envoltorio.
deal_id string

ID del acuerdo opcional para el anuncio contenedor.

Verificación

La verificación contiene información para Open Measurement, lo que facilita la medición de la visibilidad y la 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

Cadena opaca que se pasa al código de verificación de arranque.

JavaScriptResource

JavaScriptResource contiene información para la verificación a través de JavaScript.
Representación JSON
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Campos
script_url string

URI de la carga útil de JavaScript.
api_framework string

APIFramework es el nombre del framework de 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 enviar un ping en ciertas situaciones.
Representación JSON
{
  "event": string,
  "uri": string,
}
Campos
event string

Es el tipo de evento de seguimiento.
uri string

Es el evento de seguimiento al que se enviará un ping.

UniversalAdID

El UniversalAdID se usa para proporcionar un identificador único de la creatividad que se mantiene en todos los sistemas de anuncios.
Representación JSON
{
  "id_value": string,
  "id_registry": string,
}
Campos
id_value string

Es el ID de 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 del registro en el que se cataloga el ID de anuncio universal de la creatividad seleccionada.

Companion

Companion contiene información sobre 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)

Son los datos de clics de este complemento.
creative_type string

El atributo CreativeType en el nodo <StaticResource> en VAST si se trata de un elemento complementario de tipo estático.
height int32

Altura en píxeles de este anuncio complementario.
width int32

Ancho en píxeles de este anuncio complementario.
resource string

En el caso de los complementos estáticos y de iframe, esta será la URL que se cargará y mostrará. En el caso de los anuncios complementarios en HTML, será el fragmento de HTML que se debe mostrar como anuncio complementario.
type string

Tipo de este complemento. Puede ser estático, iframe o HTML.
ad_slot_id string

Es el ID del espacio de este compañero.
api_framework string

Es el framework de la API para este complemento.
tracking_events [object(TrackingEvent)]

Lista de eventos de seguimiento para este elemento complementario.

InteractiveFile

InteractiveFile contiene información sobre la creatividad interactiva (es decir, SIMID) que se debe mostrar durante la reproducción del anuncio.
Representación JSON
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Campos
resource string

URL de la creatividad interactiva.
type string

Tipo de MIME del archivo proporcionado como recurso.
variable_duration boolean

Indica si esta creatividad puede solicitar que se extienda la duración.
ad_parameters string

El valor del nodo <AdParameters> en VAST.