API lineal de inserción de anuncios dinámicos

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

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 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, proporcionada 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 recurso 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 seguimiento de la transmisión predeterminada lo inicia el cliente y se hace ping en el servidor.
Parámetros de segmentación de DoubleClick Opcional Parámetros de segmentación adicionales.
Anula los parámetros de la transmisión Opcional Anula los valores predeterminados de un parámetro de creación de transmisiones.
Autenticación de HMAC Opcional Autentica mediante un token basado en HMAC.

Cuerpo de la respuesta

Si el proceso es satisfactorio, el cuerpo de la respuesta contendrá un Stream nuevo. En el caso de las transmisiones de balizas del servidor, este Stream contiene solo 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 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 la especificación de VAST 4.1.

Método: verificación de medios

Después de encontrar un identificador de contenido multimedia del anuncio durante la reproducción, realiza una solicitud inmediatamente con la media_verification_url que se obtuvo del extremo stream anterior. Estas solicitudes no son necesarias para los flujos de balizas del servidor, en los 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 de un evento de verificación de medios.

Solicitud HTTP

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

Cuerpo de la respuesta

media verification muestra 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 o vencimiento de URL incorrectos
  • HTTP/1.1 404 Not Found si la solicitud de verificación anterior de este ID se realizó correctamente.
  • 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 anuncios se codificarán en los 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 estará encriptado y siempre comenzará con el texto "google_".

Todo el contenido de texto del marco debe agregarse a la URL de verificación del anuncio antes de realizar cada solicitud de verificación del anuncio.

Método: metadata

El extremo de metadatos en metadata_url muestra la información que se usa para compilar una IU del anuncio. 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 del contenido multimedia de los anuncios.

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

GET /{metadata_url}

Recupera información sobre metadatos de anuncios.

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.

Cómo trabajar con metadatos

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

google_1234567890

Luego, encontrarás un objeto de etiqueta llamado google_12345. En este caso, coincide con tu ID de medios de anuncios. Una vez que encuentres el objeto de prefijo de medios del anuncio correcto, podrás buscar IDs de anuncios, IDs de pausas publicitarias y el tipo de evento. Luego, se usan los IDs de anuncios para indexar los objetos ads, mientras que los IDs de pausas publicitarias se usan para indexar los objetos breaks.

Datos de respuesta

Transmisión

Stream se usa con el fin de renderizar una lista de recursos para 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

Identificador de transmisión.
stream_manifest string

El manifiesto de la transmisión, que corresponde a la lista de reproducción principal en HLS o a la MPD en DASH. Este es el único campo además de "stream_id" que está presente en la respuesta cuando se crea una transmisión de balizas del servidor.
hls_master_playlist string

URL de la playlist principal de HLS(OBSOLETA) En su lugar, usa "stream_manifest".
media_verification_url string

URL de verificación de medios.
metadata_url string

URL de metadatos de contenido multimedia del anuncio.
session_update_url string

URL de actualización de sesión.
polling_frequency number

Frecuencia de sondeo de URL de metadatos recomendada, en segundos.

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 los segmentos de la etiqueta indexados por prefijos
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

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 contenido multimedia 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

El 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 (durante el período 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 pausa válidos son: antes, durante y después.
duration number

Es la 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.
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

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

Sistema de anuncios opcional.
ad_id string

ID del anuncio opcional.
creative_id string

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

Bool opcional que indica que la entrada actual es una cortinilla de video.
icons [object(Icon)]

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

Una lista de wrappers, que 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> de VAST.
companions [object(Companion)]

Anuncios complementarios opcionales que se pueden mostrar con este anuncio.
interactive_file object(InteractiveFile)

Creatividad interactiva opcional (SIMID) que se debe mostrar durante la reproducción de anuncios

Í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 los clics en el í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 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

Es el ID del anuncio utilizado para el anuncio wrapper.
creative_id string

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

ID del anuncio de la creatividad usado para el anuncio envoltorio.
deal_id string

Es el ID del acuerdo opcional para el anuncio wrapper.

Verificación

La verificación contiene información para Open Measurement, que facilita la medición de la visibilidad y la verificación de terceros. Actualmente, solo se admiten recursos 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

Es una string 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 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 las 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; actualmente, la única opción es "verificationNotExecuted", como se especifica en la especificación de VAST 4.1.
uri string

El evento de seguimiento al que se hará 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 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,
}
Campos
click_data object(ClickData)

Los datos de clics de este complementario.
creative_type string

El atributo CreativeType en el nodo <StaticResource> de VAST si es un complemento de tipo estático.
height int32

La altura en píxeles de este anuncio complementario.
width int32

El ancho en píxeles de este 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 de HTML, este será el fragmento HTML que se debería mostrar como complementario.
type string

Tipo de este complementario. Puede ser estático, iframe o HTML.

InteractiveFile

InteractiveFile contiene información para la creatividad interactiva (es decir, SIMID) que debe mostrarse 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

El tipo MIME del archivo proporcionado como recurso.
variable_duration boolean

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

Es el valor del nodo <AdParameters> en la VAST.