Prepara al cliente para el redireccionamiento de publicación de grupos de anuncios

En esta guía, se explica cómo desarrollar una aplicación cliente para cargar una transmisión en vivo de HLS o DASH con la API de Pod serving y tu manipulador de manifiestos.

Requisitos previos

Antes de continuar, debes tener lo siguiente:

Realiza una solicitud de transmisión

Cuando el usuario seleccione una transmisión, haz lo siguiente:

  1. Realiza una solicitud POST al método del servicio de transmisión en vivo. Para obtener más detalles, consulta Método: stream.

  2. Pasa parámetros de segmentación de anuncios en formatos application/x-www-form-urlencoded o application/json. Esta solicitud registra una sesión de transmisión con la DAI de Google.

    En el siguiente ejemplo, se realiza una solicitud de transmisión:

    Codificación del formulario

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    Codificación JSON

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

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

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. En la respuesta JSON, busca el ID de sesión de transmisión y almacena otros datos para los pasos posteriores.

Metadatos de anuncios de encuesta

Para sondear los metadatos del anuncio, haz lo siguiente:

  1. Lee el valor metadata_url de la respuesta de registro de la transmisión.

  2. 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 next_delta_token.

  3. Para optimizar el ancho de banda, almacena el valor de next_delta_token de la respuesta más reciente.

  4. En tu próxima solicitud, envía ese valor como el parámetro de consulta delta_token. El servidor solo devuelve los metadatos que cambiaron desde que se generó ese token. Envía siempre el token más reciente que recibiste. No intentes analizar, modificar ni construir el token. Para obtener más detalles, consulta Método: metadata.

    En el siguiente ejemplo, se recuperan los metadatos del anuncio:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    Si se ejecuta correctamente, recibirás la respuesta PodMetadata. Si proporcionas el parámetro delta_token, la respuesta solo contendrá los anuncios, las pausas publicitarias y las etiquetas que el servidor agregó o actualizó desde que generó el token. La respuesta también contiene un nuevo valor de next_delta_token. Si alguna pausa publicitaria está desactualizada, la respuesta también incluye una lista obsolete_ad_break_ids de las pausas publicitarias que se deben quitar de la caché.

    {
  "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",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

  5. Guarda el objeto tags y combina las actualizaciones en tu caché local. Si el parámetro obsolete_ad_break_ids está presente, quita esas pausas publicitarias y los anuncios y las etiquetas asociados de tu caché.

  6. Configura un temporizador con el valor polling_frequency para solicitar metadatos de forma periódica. En cada sondeo, envía el valor de next_delta_token que se devolvió en la respuesta de metadatos más reciente como el parámetro de consulta delta_token.

Carga la transmisión en tu reproductor de video

Después de obtener el ID de sesión de la respuesta de registro, pásalo a tu manipulador de manifiestos o crea una URL de manifiesto para cargar la transmisión en un reproductor de video.

Para pasar el ID de sesión, consulta la documentación del manipulador de manifiestos. Si desarrollas un manipulador de manifiestos, consulta Manipulador de manifiestos para transmisiones en vivo.

En el siguiente ejemplo, se ensambla una URL de manifiesto:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

Cuando el reproductor esté listo, comienza la reproducción.

Cómo detectar eventos de anuncios

Verifica el formato del contenedor de tu transmisión para los metadatos cronometrados:

  • Los flujos de HLS con contenedores de flujo de transporte (TS) usan etiquetas ID3 cronometradas para transportar metadatos cronometrados. Para obtener más información, consulta Acerca del formato Common Media Application Format con HTTP Live Streaming (HLS).

  • Los flujos de DASH usan elementos EventStream para especificar eventos en el manifiesto.

  • Las transmisiones DASH usan elementos InbandEventStream cuando los segmentos contienen casillas de Mensaje de evento (emsg) para los datos de carga útil, incluidas las etiquetas ID3. Para obtener más información, consulta InbandEventStream.

  • Los flujos de CMAF, incluidos DASH y HLS, usan cuadros emsg que contienen etiquetas ID3.

Para recuperar las etiquetas ID3 de tu transmisión, consulta la guía de tu reproductor de video. Para obtener más información, consulta la guía para controlar metadatos cronometrados.

Para recuperar el ID del evento de anuncio de las etiquetas ID3, haz lo siguiente:

  1. Filtra los eventos por scheme_id_uri con urn:google:dai:2018 o https://aomedia.org/emsg/ID3.

  2. Extrae el array de bytes del campo message_data.

    En el siguiente ejemplo, se decodifican los datos de emsg en JSON:

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

  3. Filtra las etiquetas ID3 con el formato TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921

Mostrar datos del evento de anuncios

Para encontrar el objeto TagSegment, haz lo siguiente:

  1. Recupera el objeto de metadatos del anuncio tags de Sondea los metadatos del anuncio. El objeto tags es un array de objetos TagSegment.

  2. Usa el ID de evento de anuncio completo para encontrar un objeto TagSegment con el tipo progress.

  3. Usa los primeros 17 caracteres del ID del evento de anuncio para encontrar un objeto TagSegment de otros tipos.

    Dado que tu app cliente sondea los metadatos de anuncios de forma periódica, es posible que se produzca una demora entre el momento en que tu reproductor de video encuentra una etiqueta ID3 en la transmisión y el momento en que los metadatos asociados están disponibles. Si tu app cliente no encuentra una etiqueta ID3 en las etiquetas almacenadas, mantén la etiqueta en una cola y vuelve a procesarla después de la siguiente consulta de metadatos. Mantén la etiqueta en la cola hasta que finalice el procesamiento.

  4. Después de obtener el TagSegment, usa la propiedad ad_break_id como clave para encontrar el objeto AdBreak en el objeto ad_breaks de metadatos del anuncio.

    En el siguiente ejemplo, se busca un objeto AdBreak:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. Usa los datos de TagSegment y AdBreak para mostrar información sobre la posición del anuncio en la pausa publicitaria. Por ejemplo, Ad 1 of 3.

Envía pings de verificación de medios

Para cada evento de anuncio, excepto el tipo progress, envía un ping de verificación de medios. La DAI de Google descarta los eventos progress, y enviar estos eventos con frecuencia podría afectar el rendimiento de tu app.

Para generar la URL de verificación de medios completa de un evento de anuncio, haz lo siguiente:

  1. En la respuesta de transmisión, agrega el ID de evento de anuncio completo al valor media_verification_url.

  2. Realiza una solicitud GET con la URL completa:

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    Si la solicitud se completa de forma correcta, recibirás una respuesta con el código de estado 202. De lo contrario, recibirás un código de error 404.

Puedes usar el Supervisor de actividad de transmisión (SAM) para inspeccionar un registro histórico de todos los eventos de anuncios. Para obtener más información, consulta cómo supervisar y solucionar problemas de una transmisión en vivo.