API de VOD de inserción de anuncios dinámicos

La API de inserción de anuncios dinámicos te permite solicitar transmisiones de video on demand (VOD) de la DAI y hacer un seguimiento de ellas. Se admiten transmisiones HLS y DASH.

Servicio: dai.google.com

La ruta de acceso del método stream es relativa a https://dai.google.com.

Método: transmisión

Métodos
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Crea una transmisión de DAI HLS para la fuente de contenido y el ID de video determinados.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Crea una transmisión de DASH DAI para la fuente de contenido y el ID de video determinados.

Solicitud HTTP

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/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
content-source string

El ID de CMS del flujo

video-id string

El ID de video de la transmisión

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

Establece en true para crear una transmisión de indicadores del servidor. La configuración predeterminada es false. El seguimiento de la transmisión predeterminada es iniciado por el cliente y se le envía un ping al servidor.
Parámetros de segmentación de DFP Opcional Parámetros de segmentación adicionales.
Cómo anular los parámetros de transmisión Opcional Anula los valores predeterminados de un parámetro de creación de transmisiones.
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 nuevo Stream. Para las transmisiones de píxeles contadores del servidor, este Stream solo contiene los campos stream_id y stream_manifest.

Open Measurement

El campo Verifications contiene información para la verificación de Open Measurement en transmisiones que no usan píxeles contadores del servidor. Verifications contiene uno o más elementos Verification que enumeran los recursos y los metadatos que necesitas para verificar la reproducción de las creatividades con el código de medición de terceros. 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 contenido multimedia

Después de encontrar un identificador de contenido multimedia de anuncio durante la reproducción, realiza una solicitud de inmediato con el media_verification_url del extremo stream. media_verification_url es una ruta de acceso absoluta. Las solicitudes de verificación de contenido multimedia no son necesarias para las transmisiones de píxeles contadores del servidor, en las que el servidor inicia la verificación de contenido multimedia.

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

Solicitud HTTP

GET {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 contenido multimedia 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 incorrecto de la URL o a su vencimiento.
  • 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 contenido multimedia del anuncio se codificarán en los metadatos de tiempo 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 marco se debe agregar a la media_verification_url para cada solicitud de verificación de anuncios.

IDs de medios de anuncios (DASH)

Los identificadores de medios de anuncios se insertarán en el manifiesto a través del elemento EventStream de DASH.

Cada EventStream tendrá un URI de ID de esquema de urn:google:dai:2018. Contendrán eventos con el atributo messageData que contiene un ID de media de anuncio que comienza con “google_”. Todo el contenido del atributo messageData se debe agregar a media_verification_url para cada solicitud de verificación de anuncios.

Datos de respuesta

Transmisión

Se usa para renderizar una lista de todos los recursos de una transmisión creada recientemente en formato JSON .
Representación JSON
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
Campos
stream_id string

Identificador de flujo.
total_duration number

Duración de la transmisión en segundos.
content_duration number

Es la duración del contenido, sin anuncios, en segundos.
valid_for string

La transmisión de duración es válida en el formato “00h00m00s”.
valid_until string

Fecha hasta la que es válida la transmisión, en formato RFC 3339.
subtitles [object(Subtitle)]

Es una lista de subtítulos. Se omite si está vacío. Solo HLS.
hls_master_playlist string

(OBSOLETO) URL de la playlist maestra de HLS. Usa stream_manifest. Solo HLS.
stream_manifest string

Es el manifiesto del flujo. Corresponde a la playlist principal en HLS y al MPD en DASH. Este es el único campo además de "stream_id" que está presente en la respuesta cuando se crea un flujo de indicadores del servidor.
media_verification_url string

URL de verificación de contenido multimedia.
apple_tv object(AppleTV)

Información opcional específica de los dispositivos AppleTV. Solo HLS.
ad_breaks [object(AdBreak)]

Es una lista de pausas publicitarias. Se omite si está vacío.

AppleTV

AppleTV contiene información específica de los dispositivos Apple TV.
Representación JSON
{
  "interstitials_url": string,
}
Campos
interstitials_url string

URL de los anuncios intersticiales.

AdBreak

AdBreak describe una sola pausa publicitaria en la transmisión. Contiene una posición, una duración, un tipo (anuncios durante el video, previos o al final) y una lista de anuncios.
Representación JSON
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Campos
type string

Los tipos de pausa válidos son: medio, anterior y posterior.
start number

Es la posición en la transmisión en la que comienza la pausa, en segundos.
duration number

Duración de la pausa publicitaria, en segundos.
ads [object(Ad)]

Es una lista de anuncios. Se omite si está vacío.
Ad describe un anuncio en el flujo. Contiene la posición del anuncio en la pausa, la duración del anuncio y algunos metadatos opcionales.
Representación JSON
{
  "seq": number,
  "start": 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,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
Campos
seq number

Es la posición del anuncio en la pausa.
start number

Es la posición en la transmisión en la que comienza el anuncio, en segundos.
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 de anuncio opcional.
creative_id string

ID de creatividad opcional.
creative_ad_id string

ID de anuncio de creatividad opcional.
deal_id string

ID de oferta opcional.
clickthrough_url string

URL de clic opcional.
icons [object(Icon)]

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

Es una lista de wrappers. Se omite si está vacío.
events [object(Event)]

Es una lista de los eventos del anuncio.
verifications [object(Verification)]

Son entradas de verificación de medición abierta 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 las creatividades.
universal_ad_id object(UniversalAdID)

ID de anuncio universal opcional.
companions [object(Companion)]

Son los anuncios complementarios opcionales que pueden mostrarse junto con este anuncio.
interactive_file object(InteractiveFile)

Creatividad interactiva opcional (SIMID) que se debe mostrar durante la reproducción del anuncio.
skip_metadata object(SkipMetadata)

Metadatos opcionales para los anuncios que se pueden omitir. Si se establece, indica que el anuncio se puede omitir y, además, incluye instrucciones para controlar la IU de omisión y el evento de seguimiento.
extensions string

Lista opcional de todos los nodos <Extension> en el VAST.

Evento

El evento contiene un tipo de evento y una hora de presentación.
Representación JSON
{
  "time": number,
  "type": string,
}
Campos
time number

Es la hora de la presentación de este evento.
type string

Es el tipo de este evento.

Subtítulo

Subtitle describe una pista de subtítulos secundaria para la transmisión de video. Almacena dos formatos de subtítulos: TTML y WebVTT. El atributo TTMLPath contiene la URL al archivo complementario TTML y el atributo WebVTTPath contiene, de manera similar, una URL al archivo complementario WebVTT.
Representación JSON
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Campos
language string

Un código de idioma, como "en" o "de".
language_name string

Nombre descriptivo del idioma. Diferencia el conjunto específico de subtítulos si existen varios conjuntos para el mismo idioma.
ttml string

URL opcional al archivo adicional TTML.
webvtt string

URL opcional al archivo adicional WebVTT.

SkipMetadata

SkipMetadata proporciona la información necesaria para que los clientes controlen los eventos de omisión de anuncios que se pueden omitir.
Representación JSON
{
  "offset": number,
  "tracking_url": string,
}
Campos
offset number

El desplazamiento indica la cantidad de tiempo en segundos dentro del anuncio que el reproductor debe esperar para renderizar el botón Omitir. Se omite si no se proporciona en el VAST.
tracking_url string

TrackingURL contiene una URL a la que se debe hacer ping en el evento de omisión.

Ícono

El ícono contiene información sobre un ícono 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 un clic en 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 de oferta si no existe.
Representación JSON
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Campos
system string

Es el identificador del sistema de anuncios.
ad_id string

Es el ID del anuncio que se usa para el anuncio del wrapper.
creative_id string

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

Es el ID del anuncio de creatividad que se usa para el anuncio del wrapper.
deal_id string

ID de acuerdo opcional para el anuncio de wrapper.

Verificación

La verificación contiene información para 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

Es una 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 a 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 le enviará un 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 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 del anuncio universal de la creatividad seleccionada.

Companion

El elemento complementario contiene información para 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 elemento complementario.
creative_type string

El atributo CreativeType en el nodo <StaticResource> en el archivo VAST si se trata de una creatividad complementaria 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 anuncios complementarios estáticos y de iframe, esta será la URL que se cargará y mostrará. En el caso de los anuncios complementarios HTML, este será el fragmento de HTML que se debe mostrar como el anuncio complementario.
type string

Es el tipo de este elemento complementario. Puede ser estático, iframe o HTML.
ad_slot_id string

El ID del espacio para este elemento complementario.
api_framework string

El framework de la API para este dispositivo complementario.
tracking_events [object(TrackingEvent)]

Lista de eventos de seguimiento de este dispositivo complementario.

InteractiveFile

InteractiveFile contiene información para la creatividad interactiva (es decir, el 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

Es la URL de la creatividad interactiva.
type string

Es 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 el archivo VAST.