Usar una integración personalizada

Antes de empezar

En esta guía solo se incluyen las instrucciones de reproducción cuando no se usa el SDK de inserción dinámica de anuncios de IMA.

Asegúrate de haber completado los pasos que se indican en el artículo Integrar Google Ad Manager (GAM) con emisiones en directo.

Si el SDK de IMA no está disponible para la plataforma que quieres usar, tu aplicación deberá llamar a las APIs necesarias y activar las impresiones de anuncios por sí misma.

Para ello, necesitará la siguiente información:

OAUTH_TOKEN

Enviar una solicitud de registro de stream a Ad Manager

Envía una solicitud POST al endpoint de registro de la emisión. A cambio, recibirás una respuesta JSON que contiene el ID de la emisión que debes enviar a la API de costura de vídeo.

punto final de API

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

Parámetros de ruta

Parámetros del cuerpo codificados en formularios

Conjunto opcional de parámetros de segmentación codificados en formato de formulario.

Respuesta (JSON)

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

Respuesta de ejemplo

{
  "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 error, se devuelven códigos de error HTTP estándar sin cuerpo de respuesta JSON.

Analiza la respuesta JSON y almacena los valores pertinentes.

Generar el URI de reproducción de la sesión

Haz una solicitud POST al endpoint /livesessions de la API Video Stitcher para crear una sesión en directo. A cambio, recibirás una respuesta JSON que contiene el manifiesto de la emisión para cargarlo en tu reproductor de vídeo.

punto final de API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Parámetros de ruta

Parámetro de encabezado de autorización

OAUTH_TOKEN

Parámetros del cuerpo codificados en JSON

Respuesta (JSON)

Solicitud de ejemplo (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

Respuesta de ejemplo

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

Una vez que se haya recibido la respuesta, podrá reproducir la emisión en directo con anuncios insertados haciendo referencia al URI de reproducción de la sesión del campo playUri del objeto de respuesta.

La API Video Stitcher genera un ID de sesión único para cada solicitud, que se puede obtener de la última sección del campo name del objeto de respuesta.

Las sesiones inactivas caducan al cabo de 5 minutos. Una sesión se considera inactiva si no se ha realizado ninguna solicitud de manifiesto en un periodo determinado.

Sondea los nuevos metadatos de AdBreak.

La aplicación es responsable de recuperar los metadatos de cada pausa publicitaria para saber qué impresiones se deben activar. Para ello, debes configurar un temporizador que consulte periódicamente las APIs de inserción dinámica de anuncios metadata_url para obtener información sobre los anuncios. El intervalo de sondeo se especifica en el campo polling_frequency de la respuesta de registro de la secuencia.

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

Almacena estos valores después de cada sondeo para asociar eventos de metadatos temporizados en tu flujo de vídeo.

Solicitud de ejemplo (cURL)

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

Respuesta de ejemplo

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },
      ...
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/...",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },
      ...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },
      ...
   }
}

Procesar eventos ID3 y registrar eventos de reproducción

Para verificar que se han producido eventos específicos en un flujo de vídeo, sigue estos pasos para gestionar eventos ID3:

1. Almacena los eventos multimedia en una cola y guarda cada ID multimedia junto con su marca de tiempo, si el reproductor lo muestra.
2. En cada actualización de tiempo del reproductor o con una frecuencia definida (se recomienda 500 ms), comprueba la cola de eventos multimedia para ver los eventos reproducidos recientemente comparando las marcas de tiempo de los eventos con el cabezal de reproducción.
3. En el caso de los eventos multimedia que haya confirmado que se han reproducido, consulte el tipo buscando el ID de contenido multimedia en las etiquetas de inserción de anuncios almacenadas. Ten en cuenta que el objeto de las etiquetas de inserción publicitaria solo contiene una versión truncada del ID de contenido multimedia, limitada a los 10 primeros dígitos después del prefijo google_, por lo que no hay una coincidencia directa entre los IDs de verificación de contenido multimedia ID3 y las claves del objeto de las etiquetas. De esta forma, se evita que se envíen pings de verificación de eventos antes de que llegue el evento ID3. Para generar la URL de verificación de contenido multimedia completa de un evento de anuncio, añade el ID de evento de anuncio completo al valor de media_verification_url de la respuesta de creación de la emisión.
4. Usa los eventos "progress" para hacer un seguimiento de si un usuario está en una pausa publicitaria. No envíe estos eventos al endpoint de verificación de medios para evitar un código de error HTTP. En el caso de otros tipos de eventos, añade el ID de contenido multimedia a la URL de verificación de contenido multimedia y haz una solicitud GET para monitorizar la reproducción.
5. Quita el evento multimedia de la cola.

punto final de API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parámetros de ruta

Valores de retorno esperados

Solicitud de ejemplo (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Respuesta de ejemplo

HTTP/1.1 204 No Content

Limitaciones

Si usas la API en vistas web, se aplican las siguientes limitaciones en relación con la segmentación:

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