Usar una integración personalizada

Antes de empezar

En este documento solo se tratan las instrucciones de reproducción cuando no se usa el SDK de DAI de IMA.

Asegúrate de haber completado los pasos que se indican en el artículo Integrar Google Ad Manager (GAM) con recursos de vídeo bajo demanda.

Si el SDK de IMA no está disponible para la plataforma que quieres usar, tu aplicación tendrá que llamar a las APIs necesarias y activar las verificaciones de medios publicitarios 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 tu servidor de manipulación de manifiestos y los endpoints de la API Pod Serving asociados.

punto final de API

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

Parámetros de ruta

Parámetros del cuerpo codificados en JSON

targeting_parameters

Un conjunto de parámetros de segmentación opcionales codificados en JSON.

Respuesta (JSON)

Solicitud de ejemplo (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

Respuesta de ejemplo

{
  "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 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 una sesión de VOD de Cloud Video Stitcher

Envía una solicitud POST al endpoint de registro de sesiones de VOD. A cambio, recibirás una respuesta JSON que contiene el URI del archivo de manifiesto de la emisión y los metadatos sobre las pausas publicitarias, los anuncios y los eventos publicitarios.

punto final de API

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

Parámetros de ruta

Parámetros del cuerpo codificados en JSON

{
  "networkCode":"NETWORK_CODE",
  "streamId":"STREAM_ID"
}
      

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/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Respuesta de ejemplo

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

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

Solicitar metadatos de pod de anuncios a Ad Manager

Envía una solicitud GET a la metadata_url que recibiste cuando registraste tu stream en Ad Manager. Este paso debe realizarse después de que hayas recibido el manifiesto combinado de la URI de reproducción.

A cambio, recibes un objeto JSON que describe las pausas publicitarias, los anuncios y los eventos publicitarios de la emisión.

Punto final de la API

GET: METADATA_URL
Host: dai.google.com

Respuesta (JSON)

Solicitud de ejemplo (cURL)

curl METADATA_URL

Ejemplo de respuesta JSON

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

Almacena estos valores para asociarlos a eventos de metadatos sincronizados en tu flujo de vídeo.

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