App cliente de reproductor de video para transmisiones de VOD

La API de DAI Pod Serving de Google 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 Entrega de Pods y lograr una funcionalidad similar con el SDK de DAI de IMA. Si tienes preguntas específicas sobre la funcionalidad compatible, comunícate con tu administrador de cuentas de Google.

La API de entrega de pods admite transmisiones de entrega de pods en los protocolos de transmisión HLS o MPEG-DASH. Esta guía se centra en las transmisiones HLS y destaca las diferencias clave entre HLS y MPEG-DASH en pasos específicos.

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

Realice una solicitud de registro de transmisión a Ad Manager

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

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 de acceso

{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 el ID de fuente del contenido (cmsid), el ID de video (vid) y los parámetros de segmentación del anuncio. Obligatorio

Respuesta JSON

media_verification_url La URL base para hacer ping a eventos de seguimiento de reproducción. Para crear una URL completa de verificación de medios, se agrega un ID de evento de anuncio a esta URL base.
metadata_url Es la URL para solicitar metadatos del grupo de anuncios.
stream_id Es la cadena que se usa para identificar la sesión de transmisión actual.
valid_for La cantidad de tiempo restante 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 La hora a la que vence la sesión de transmisión actual, como una string 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":{"cmsid":"12345","vid":"sample-video"}}' \
     -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, los códigos de error de HTTP estándar se muestran sin cuerpo de respuesta JSON.

Analizar la respuesta JSON y almacenar los valores relevantes

Solicita el manifiesto de transmisión desde el manipulador de manifiestos

Cada manipulador de manifiestos tiene diferentes formatos de solicitud y respuesta. Comunícate con el proveedor del manipulador para comprender sus requisitos específicos. Si deseas implementar tu propio manipulador de manifiestos, lee la guía de manipulación 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 este pueda compilar manifiestos específicos de la sesión. A menos que el manipulador de manifiestos lo indique explícitamente, la respuesta a tu solicitud de manifiesto es una transmisión de video por Internet que incluye 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, luego, inicia la reproducción.

Solicita metadatos de grupos de anuncios de Ad Manager

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

tags Es un conjunto de pares clave-valor que contiene todos los eventos de anuncios que aparecen en la transmisión. Las claves son los primeros 17 caracteres de un ID de evento de anuncio que aparecen en los metadatos temporizados 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 del 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 principio del anuncio.
firstquartile Se activa al final del primer cuartil.
midpoint Se activa en el punto medio del anuncio.
thirdquartile Se activa al final del tercer cuartil.
complete Se activa al final del anuncio.
progress Se activa periódicamente durante todo el 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 la transmisión. Las claves son IDs de anuncios que coinciden con los valores encontrados 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 en 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 se admite.
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 pausa publicitaria que coinciden con valores que se encuentran en los objetos tags y ads mencionados anteriormente. Cada valor es un objeto que contiene los siguientes parámetros:
type Es 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 temporizados en la 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
    },
    ...
  }
}

Escucha eventos de anuncios

Detecta metadatos temporizados a través de eventos de anuncios activados en la transmisión de audio o video de tu reproductor de video.

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

La XXX en TXXX no es un marcador de posición. La cadena TXXX es el ID de etiqueta de 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 emsg en banda que emulan las 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 de message_data, sin el prefijo ID3TXXX, es el ID del evento del anuncio.

Cuadro de mensaje electrónico de ejemplo

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

Si el ID del evento de anuncios es google_1234567890123456789, la respuesta se ve 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 del reproductor multimedia presentan automáticamente los eventos emsg que emulan etiquetas ID3 como etiquetas nativas ID3. En este caso, las transmisiones MP4 presentan etiquetas ID3 idénticas que las MPEG_TS.

Actualiza la IU de la app cliente de reproductor de video

Cada ID del evento de anuncios se puede hacer coincidir con una clave en el objeto tags del paso 4. Hacer coincidir estos valores es un proceso de dos pasos:

  1. Busca una clave que coincida con el ID completo del evento de anuncio en el objeto tags. 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 completo del evento de anuncio, busca en el objeto tags una clave que coincida con los primeros 17 caracteres del ID del 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 jugador y muestra una superposición que describa la posición actual del anuncio 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 medios

Se debe enviar un ping de verificación de medios a Ad Manager cada vez que se recibe un evento de anuncio con un tipo que no sea progress.

Para generar la URL completa de verificación de medios 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, a su vez, recibirás una respuesta HTTP con el código de estado 202. De lo contrario, recibirás el código de error de HTTP 404.

Ejemplo de solicitud (cURL)

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

Ejemplo de respuesta correcta

HTTP/1.1 202 Accepted

Recursos adicionales