App cliente de reproductor de video para transmisiones en vivo

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

En esta guía, se muestra cómo interactuar con la API de Pod Serving y lograr funcionalidades similares con el SDK de IMA de DAI. Si tienes preguntas específicas sobre función compatible, comunícate con tu administrador de cuentas de Google.

La API de Pod Serving admite transmisiones de entrega de grupos de anuncios en HLS o MPEG-DASH de transmisión continua. Esta guía se enfoca en las transmisiones HLS y se destaca la clave diferencias entre HLS y MPEG-DASH en pasos específicos.

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

Realice una solicitud de registro de transmisión a la API de DAI Pod Serving

Realizar una solicitud POST al extremo de registro de transmisión A su vez, recibirás un Respuesta JSON que contiene el ID de flujo para enviar a la manipulación del manifiesto y extremos de la API de Pod Serving asociados.

extremo de API

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Parámetros de ruta

{network_code} Su código de red de Google Ad Manager 360
{custom_asset} Es el identificador personalizado asociado a este evento en Google Ad Manager.

Parámetros del cuerpo con codificación de formulario

Un conjunto opcional de formularios codificados parámetros de segmentación

JSON de la respuesta

media_verification_url La URL base para hacer ping a eventos de seguimiento de reproducción. Una verificación de medios completa La URL se forma al agregar un ID del evento del anuncio a esta URL base.
metadata_url Es la URL para solicitar los metadatos del grupo de anuncios.
stream_id Es la cadena utilizada para identificar la sesión de transmisión actual.
valid_for El tiempo restante hasta que caduque 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 El momento en que vence la sesión de transmisión actual, como ISO 8601 string de fecha y hora en yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm de un conjunto de datos tengan un formato común.

Solicitud de ejemplo (cURL)

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

Ejemplo de respuesta

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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

Analiza la respuesta JSON y almacena los valores relevantes.

Cómo solicitar el manifiesto de transmisión desde el manipulador de manifiestos

Cada manipulador de manifiestos tiene diferentes formatos de solicitud y respuesta. Contactar con su proveedor de manipuladores para comprender sus requisitos específicos. Si estás para implementar tu propio manipulador de manifiestos, lee el manipor de manifiestos guía para comprender la requisitos para este componente.

En general, debes pasar el ID de transmisión que devolvió el el extremo de registro anterior a tu manipulador de manifiestos para que compile manifiestos específicos de la sesión. A menos que se indique explícitamente en tu manifiesto manipulador, la respuesta a la solicitud del manifiesto es una transmisión de video por Internet que contiene el contenido y los anuncios.

Solicitud de ejemplo (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 e inicia la reproducción.

Encuesta para metadatos nuevos de AdBreak

La aplicación se encarga de recuperar los metadatos de cada pausa publicitaria, por lo que sabe qué impresiones deben activarse. Para lograrlo, definirás temporizador para sondear periódicamente las APIs de DAI metadata_url en busca de un anuncio nuevo información. El intervalo de sondeo se especifica en el archivo polling_frequency en la respuesta de registro de transmisión.

A cambio, recibirás un objeto JSON que contiene los siguientes parámetros:

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

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

ad El ID de un anuncio que coincide con una clave del objeto ads.
ad_break_id El ID de una pausa publicitaria que coincide con una clave en 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 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 publica un anuncio está sonando el descanso.
ads Es un conjunto de pares clave-valor que describen todos los anuncios que aparecen en la transmisión. El Las claves son IDs de anuncios que coinciden con los valores encontrados en el objeto tags. que se mencionaron anteriormente. Cada valor es un objeto que contiene los siguientes parámetros:
ad_break_id El ID de una pausa publicitaria que coincide con una clave en ad_breaks .
position La posición en la que aparece este anuncio dentro del conjunto de anuncios del anuncio de salto, 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 tags. y ads, como se muestra más arriba. Cada valor es un objeto Contiene los siguientes parámetros:
type Es el tipo de pausa publicitaria. Los tipos de pausas publicitarias son pre (anuncios previos 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 incluidos en esta pausa publicitaria.

Almacena estos valores después de cada sondeo para asociar eventos de metadatos temporizados dentro tu transmisión de video por Internet.

Solicitud de ejemplo (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

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

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

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

Ejemplo de etiqueta ID3

TXXXgoogle_1234567890123456789

Para las transmisiones MP4, se envían como eventos emsg en banda que emulan ID3 v2.3. rótulos nuevos rápidamente. Cada cuadro de emsg relevante tiene un valor scheme_id_uri de cualquiera de las siguientes opciones: 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 elemento El prefijo ID3TXXX es el ID del evento de anuncio.

Ejemplo de cuadro de emsg

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

Si el ID del evento del anuncio es google_1234567890123456789, la respuesta se ve así: esto:

{
  "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 emsg que emulan ID3. como etiquetas de ID3 nativas. En este caso, las transmisiones de MP4 presentan etiquetas ID3 idénticas. como MPEG_TS.

Actualiza la IU de la app de reproductor de video del cliente

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

  1. Busca en el objeto tags una clave que coincida con el ID completo del evento de anuncios. Si si encuentra una coincidencia, recupera el tipo de evento y su ad asociado. ad_break. Estos eventos deben tener el tipo progress.

    Si no se encuentra una coincidencia para el ID completo del evento del anuncio, comprueba el tags para 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 de tu reproductor. Por ejemplo, cuando recibes un evento de start o el primer evento de progress, oculta el botón de búsqueda de tu jugador controles y mostrará una superposición que describa la posición actual del anuncio dentro del anuncio pausa, por ejemplo: "Anuncio 1 de 3".

Ejemplo 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"
  },
  ...
}

Enviar pings de verificación de medios

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

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

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

Solicitud de ejemplo (cURL)

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

Ejemplo de respuesta exitosa

HTTP/1.1 202 Accepted

Recursos adicionales