App cliente de reproductor de video para transmisiones de VOD

La API de Google DAI Pod Serving te permite realizar la inserción de anuncios del servidor con la tecnología de Google Ads y, al mismo tiempo, mantener el control de tu propia unión de videos.

En esta guía, se muestra cómo interactuar con la API de Publicación de grupos de anuncios y lograr una funcionalidad similar con el SDK de DAI de IMA. Si tienes preguntas específicas sobre las funciones compatibles, comunícate con tu administrador de Cuentas de Google.

La API de Publicación de grupos de anuncios admite transmisiones de Publicación de grupos de anuncios en protocolos de transmisión HLS o MPEG-DASH. En esta guía, se enfocan las transmisiones HLS y se destacan las diferencias clave entre HLS y MPEG-DASH en pasos específicos.

Para integrar la API de Pod Serving en tu app para transmisiones de VOD, completa los siguientes pasos:

Realiza una solicitud de registro de flujo a Ad Manager

Realiza una solicitud POST al extremo de registro de flujos. A su vez, recibes una respuesta JSON que contiene el ID de transmisión para enviar a tu servidor de manipulación de manifiestos y a los extremos de la API de Pod Serving asociados.

extremo de API

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parámetros de ruta

{network_code} Tu código de red de Google Ad Manager 360

Parámetros del cuerpo JSON

targeting_parameters Es un objeto JSON que contiene los parámetros de segmentación del anuncio. Obligatorio

JSON de la respuesta

media_verification_url Es la URL base para enviar un ping a los eventos de seguimiento de reproducción. Para obtener una URL de verificación de medios completa, se debe adjuntar un ID de evento de anuncio a esta URL base.
metadata_url Es la URL para solicitar los metadatos del grupo de anuncios.
stream_id Es la cadena que se usa para identificar la sesión de transmisión actual.
valid_for Es la cantidad de tiempo que queda hasta que venza la sesión de transmisión actual, en formato dhms (días, horas, minutos y segundos). Por ejemplo, 2h0m0.000s representa una duración de 2 horas.
valid_until Es la hora a la que vence la sesión de transmisión actual, como una cadena de fecha y hora ISO 8601 en formato yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Ejemplo de solicitud (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

Ejemplo de respuesta

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

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 valores relevantes.

Solicita el manifiesto de transmisión al manipulador de manifiestos

Cada manipulador de manifiestos tiene diferentes formatos de solicitud y respuesta. Comunícate con tu proveedor de manipuladores para conocer sus requisitos específicos. Si vas a implementar tu propio manipulador de manifiestos, lee la guía del manipulador de manifiestos para comprender los requisitos de este componente.

En general, debes pasar el ID de flujo que mostró el extremo de registro anterior a tu manipulador de manifiestos para que compile manifiestos específicos de la sesión. A menos que el manipulador de manifiestos lo indique de forma explícita, la respuesta a tu solicitud de manifiesto es una transmisión de video que contiene contenido y anuncios.

Ejemplo de solicitud (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Respuesta de ejemplo (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

Reproducir la transmisión

Carga el manifiesto que recibiste del servidor de manipulación de manifiestos en un reproductor de video y comienza la reproducción.

Cómo solicitar metadatos de grupos de anuncios desde Ad Manager

Realiza una solicitud GET al metadata_url que recibiste en el paso uno. Este paso debe ocurrir después de que hayas recibido el manifiesto unido de tu manipulador de manifiestos. A cambio, recibirás un objeto JSON que contiene los siguientes parámetros:

tags Es un conjunto de pares clave-valor que contienen todos los eventos de anuncios que aparecen en el flujo. Las claves son los primeros 17 caracteres del ID de un evento de anuncio que aparecen en los metadatos de tiempo de la transmisión o, en el caso de los eventos de tipo progress, el ID completo del evento de anuncio.

Cada valor es un objeto que contiene los siguientes parámetros:

ad Es el ID de un anuncio que coincide con una clave en el objeto ads.
ad_break_id Es el ID de una pausa publicitaria que coincide con una clave en el objeto ad_breaks.
type Es el tipo de evento de anuncio. Los tipos de eventos de anuncios son los siguientes:
start Se activa al comienzo del anuncio.
firstquartile Se activa al final del primer cuartil.
midpoint Se activa en el punto medio del anuncio.
thirdquartile Se despidió al final del tercer cuartil.
complete Se activa al final del anuncio.
progress Se activa periódicamente a lo largo del anuncio para notificar a la app que se está reproduciendo una pausa publicitaria.
ads Es un conjunto de pares clave-valor que describen todos los anuncios que aparecen en el flujo. Las claves son IDs de anuncios que coinciden con los valores que se encuentran en el objeto tags mencionado anteriormente. Cada valor es un objeto que contiene los siguientes parámetros:
ad_break_id Es el ID de una pausa publicitaria que coincide con una clave en el objeto ad_breaks.
position Es la posición en la que aparece este anuncio dentro del conjunto de anuncios de la pausa publicitaria, en segundos de punto flotante.
duration Es la duración del anuncio en segundos de punto flotante.
clickthrough_url Es la URL que se debe abrir cuando un usuario interactúa con este anuncio, si es compatible.
ad_breaks Es un conjunto de pares clave-valor que describen todas las pausas publicitarias que aparecen en la transmisión. Las claves son IDs de pausas publicitarias que coinciden con los valores que se encuentran en los objetos tags y ads mencionados anteriormente. Cada valor es un objeto que contiene los siguientes parámetros:
type El tipo de pausa publicitaria. Los tipos de pausas publicitarias son pre (anuncio previo al video), mid (anuncio durante el video) y post (anuncio al final del video).
duration Es la duración de la pausa publicitaria en segundos de punto flotante.
ads Es la cantidad de anuncios en esta pausa publicitaria.

Almacena estos valores para asociarlos con eventos de metadatos cronometrados en tu transmisión de video.

Ejemplo de solicitud (cURL)

curl https://dai.google.com/.../metadata

Ejemplo de respuesta

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Cómo detectar eventos de anuncios

Escucha metadatos sincronizados a través de eventos de anuncios activados en la transmisión de audio/video de tu reproductor de video.

En el caso de las transmisiones MPEG-TS, los metadatos aparecen como etiquetas ID3 v2.3 en la banda. Cada etiqueta de metadatos tiene el ID TXXX, y el valor comienza con la cadena google_ seguida de una serie de caracteres. Este valor es el ID del evento de anuncio.

El XXX en TXXX no es un marcador de posición. La cadena TXXX es el ID de etiqueta ID3 reservado para "texto definido por el usuario".

Ejemplo de etiqueta ID3

TXXXgoogle_1234567890123456789

En el caso de las transmisiones MP4, se envían como eventos de emsg en la banda que emulan etiquetas ID3 v2.3. Cada cuadro de emsg relevante tiene un valor scheme_id_uri de https://aomedia.org/emsg/ID3 o https://developer.apple.com/streaming/emsg-id3 y un valor message_data que comienza con ID3TXXXgoogle_. Este valor message_data, sin el prefijo ID3TXXX, es el ID del evento de anuncio.

Ejemplo de cuadro de mensaje electrónico

La estructura de los datos puede variar según la biblioteca de tu reproductor multimedia.

Si el ID del evento de anuncio es google_1234567890123456789, la respuesta se verá de la siguiente manera:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

Algunas bibliotecas de reproductores multimedia presentan automáticamente eventos de emsg que emulan etiquetas ID3 como etiquetas ID3 nativas. En este caso, las transmisiones de MP4 presentan etiquetas ID3 idénticas a las de MPEG_TS.

Actualiza la IU de la app cliente del reproductor de video

Cada ID de evento de anuncio puede coincidir con una clave en el objeto tags del paso 4. La coincidencia de estos valores es un proceso de dos pasos:

  1. Busca una clave en el objeto tags que coincida con el ID completo del evento de anuncio. Si se encuentra una coincidencia, recupera el tipo de evento y sus objetos ad y ad_break asociados. Estos eventos deben tener el tipo progress.

    Si no se encuentra una coincidencia para el ID de evento de anuncio completo, verifica el objeto tags en busca de una clave que coincida con los primeros 17 caracteres del ID de evento de anuncio. Recupera el tipo de evento y los objetos ad y ad_break asociados. Esto debería recuperar todos los eventos con tipos distintos de progress.

  2. Usa esta información recuperada para actualizar la IU del reproductor. Por ejemplo, cuando recibas un start o el primer evento progress, oculta los controles de búsqueda del reproductor y muestra una superposición que describa la posición del anuncio actual en la pausa publicitaria, por ejemplo: "Anuncio 1 de 3".

Ejemplos de IDs de eventos de anuncios

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Ejemplo de objeto de etiquetas

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

Envía pings de verificación de contenido multimedia

Se debe enviar un ping de verificación de contenido multimedia a Ad Manager cada vez que se recibe un evento de anuncio con un tipo distinto de progress.

Para generar la URL de verificación de medios completa de un evento de anuncio, agrega el ID completo del evento de anuncio al valor media_verification_url de la respuesta de registro de transmisión.

Realiza una solicitud GET con la URL completa. Si la solicitud de verificación se realiza correctamente, recibirás una respuesta HTTP con el código de estado 202. De lo contrario, recibirás el código de error HTTP 404.

Ejemplo de solicitud (cURL)

curl https://{...}/media/google_5555555555123456789

Ejemplo de respuesta correcta

HTTP/1.1 202 Accepted

Recursos adicionales