Cómo administrar las transmisiones en vivo de DAI

La API de DAI de Google te permite implementar transmisiones habilitadas para la DAI de Google en entornos en los que no se admite la implementación del SDK de IMA. Te recomendamos que sigas usando IMA en las plataformas en las que se admite el SDK de IMA.

Te recomendamos usar la API de DAI en las siguientes plataformas:

  • Samsung Smart TV (Tizen)
  • LG TV
  • HbbTV
  • Xbox (apps de JavaScript)
  • KaiOS

La API admite las capacidades básicas que proporciona el SDK de IMA DAI. Si tienes preguntas específicas sobre la compatibilidad o las funciones admitidas, comunícate con tu administrador de cuentas de Google.

Implementa la API de DAI para transmisiones EN VIVO

La API de DAI admite transmisiones lineales (EN VIVO) con los protocolos HLS y DASH. Los pasos que se describen en esta guía se aplican a ambos protocolos.

Para integrar la API en tu app para transmisiones EN VIVO, completa los siguientes pasos:

1. Cómo solicitar una transmisión

Para solicitar una transmisión en vivo desde la API de DAI, realiza una llamada POST al extremo de transmisión. La respuesta JSON contiene el manifiesto de la transmisión, así como los valores y los extremos de la API de DAI asociados.

Ejemplo de cuerpo de la solicitud

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Ejemplo de cuerpo de respuesta

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Respuesta de error

En caso de errores, se muestran códigos de error HTTP estándar sin cuerpo de respuesta JSON.

Analiza la respuesta JSON y almacena los siguientes valores:

stream_id
Este valor se puede usar para identificar el flujo devuelto.
stream_manifest
Esta URL se pasa a tu reproductor de contenido multimedia para la reproducción de la transmisión.
media_verification_url
Esta URL es el extremo base para hacer un seguimiento de los eventos de reproducción.
metadata_url
Esta URL se usa para sondear información periódica sobre los próximos eventos de transmisión.
session_update_url
Esta URL se usa para actualizar los parámetros de la solicitud de transmisión que se envían durante la solicitud de transmisión inicial. Ten en cuenta que los parámetros de esta solicitud reemplazan todos los parámetros establecidos para la transmisión anterior.
polling_frequency
Frecuencia, en segundos, con la que se solicitan metadatos de AdBreak actualizados a la API de DAI.

2. Sondea nuevos metadatos de AdBreak

Configura un temporizador para sondear los nuevos metadatos de AdBreak en la frecuencia de sondeo, usando la URL de metadatos. Si no se especifica en la respuesta de transmisión, el intervalo recomendado predeterminado es de 10 segundos.

Para optimizar el ancho de banda, haz lo siguiente:

  1. Realiza una solicitud GET inicial al extremo metadata_url.
    • Omite el parámetro de consulta delta_token. Este proceso permite que el servidor devuelva los metadatos completos de la ventana de la grabadora de video digital (DVR) de la transmisión. La ventana de DVR contiene el período de la transmisión disponible para que un usuario retroceda y reproduzca. La respuesta incluye un campo de objeto next_delta_token.
  2. Almacena metadatos en el cliente.
  3. Realiza llamadas posteriores con el valor de next_delta_token que devuelve la respuesta más reciente. Cada respuesta contiene un valor next_delta_token. Envía siempre el valor más reciente que recibas.
  4. Actualiza los metadatos almacenados para combinar los cambios y quitar los cortes publicitarios obsoletos.

No intentes analizar, construir ni modificar el token delta. El formato del token puede cambiar. Almacena el token tal como lo recibiste y pásalo sin cambios en la próxima solicitud.

Ejemplo de solicitud inicial

La solicitud inicial no toma parámetros de consulta y devuelve los metadatos completos:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Ejemplo de solicitud posterior

Cada solicitud posterior pasa el valor de next_delta_token de la respuesta anterior como el parámetro delta_token. La respuesta contiene lo siguiente:

  • Anuncios
  • Pausas para anuncios
  • Son las etiquetas que el servidor agregó o actualizó desde que emitió el token.
  • Una lista obsolete_ad_break_ids de pausas publicitarias que se quitarán de los metadatos almacenados

El servidor omite los cortes publicitarios que no cambiaron. En el siguiente ejemplo, se muestra una votación posterior en la que se usa el token delta para recuperar solo estos cambios recientes:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Si se ejecuta de forma correcta, verás un resultado similar al siguiente:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. Cómo detectar eventos de ID3 y hacer un seguimiento de los eventos de reproducción

Para verificar que se hayan producido eventos específicos en una transmisión de video, sigue estos pasos para controlar los eventos ID3:

  1. Almacena los eventos de medios en una cola y guarda cada ID de medio junto con su marca de tiempo (si el reproductor la muestra).
  2. En cada actualización de tiempo del reproductor o con una frecuencia establecida (se recomienda 500 ms), compara las marcas de tiempo de los eventos con el cabezal de reproducción para verificar si hay eventos reproducidos recientemente en la cola de eventos de medios.
  3. En el caso de los eventos de medios que confirmes que se reprodujeron, verifica el tipo buscando el ID de medios en las etiquetas de pausas publicitarias almacenadas. Ten en cuenta que las etiquetas almacenadas solo contienen un prefijo del ID de los medios, por lo que no es posible una coincidencia exacta.
  4. Dado que tu app de reproductor de video sondea la URL de metadatos periódicamente, es posible que se produzca una demora entre el momento en que el reproductor de video encuentra una etiqueta ID3 en la transmisión y el momento en que los metadatos asociados están disponibles. Si no se encuentra una etiqueta ID3 en las etiquetas almacenadas, mantén la etiqueta en una cola y vuelve a procesarla después de la siguiente actualización de metadatos. Mantén el evento en la cola hasta que finalice el procesamiento.
  5. Después de encontrar la etiqueta en los metadatos, compara el campo type de la etiqueta con los tipos de eventos de anuncios que se indican en la siguiente sección. Para hacer un seguimiento de si el reproductor de video está reproduciendo una pausa publicitaria, usa eventos con el valor progress del campo type. No envíes estos eventos al extremo de verificación de medios. Para todos los demás tipos de eventos, agrega el ID de medios al endpoint de verificación de medios y realiza una solicitud GET para hacer un seguimiento de la reproducción.
  6. Quita el evento de medios de la cola.

Tipos de eventos de anuncios

Cada etiqueta del objeto de metadatos tags tiene uno de los siguientes tipos de eventos:

Tipo de evento Descripción
start Se ejecuta al comienzo del anuncio.
firstquartile Se ejecuta al final del primer cuartil del anuncio.
midpoint Se ejecuta en el punto medio del anuncio.
thirdquartile Se ejecuta al final del tercer cuartil del anuncio.
complete Se ejecuta al final del anuncio.
progress Se ejecuta periódicamente durante una pausa publicitaria para indicar que se está reproduciendo una pausa publicitaria. No envíes estos eventos al extremo de verificación de medios.

Ejemplo de solicitud

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Ejemplos de respuestas

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Puedes verificar los eventos de seguimiento en el Supervisor de actividad de transmisión.

4. Actualiza los parámetros de la sesión de transmisión en vivo

Es posible que desees ajustar los parámetros de sesión después de crear una transmisión. Para ello, realiza una solicitud a la URL de actualización de la sesión.

Ejemplo de cuerpo de la solicitud

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Ejemplo de cuerpo de respuesta

Successful response would be to look for - HTTP/1.1 200

Limitaciones

Si usas la API en WebView, se aplican las siguientes limitaciones con respecto a la segmentación:

  • UserAgent: El parámetro user agent se pasa como un valor específico del navegador en lugar de la plataforma subyacente.
  • rdid, idtype, is_lat: El ID del dispositivo no se pasa correctamente, lo que limita las capacidades de las siguientes funciones:
    • Limitación de frecuencia
    • Rotación secuencial de anuncios
    • Segmentación y orientación del público

Prácticas recomendadas

Ten en cuenta que el extremo de metadatos para los índices de transmisiones en vivo se basa en el prefijo de la etiqueta ID3 correspondiente. Esto se diseñó de esta manera para evitar el uso del extremo de metadatos para hacer ping de inmediato a todos los nodos de verificación.

Recursos adicionales