Cómo usar una integración personalizada

Antes de comenzar

En esta guía, solo se abordan las instrucciones de reproducción en ausencia del SDK de DAI de IMA.

Asegúrate de haber completado los pasos que se indican en Cómo integrar Google Ad Manager (GAM) con transmisiones en vivo con anterioridad.

Nota: Te recomendamos que uses el SDK de DAI de IMA en las plataformas en las que es compatible.

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

Para ello, necesitarás la siguiente información:

Ubicación	La región de Google Cloud en la que se creó tu configuración activa: LOCATION
Número de proyecto	El número de proyecto del proyecto de Google Cloud que usa la API de Video Stitcher: PROJECT_NUMBER
Token de OAuth	El token de OAuth de corta duración de una cuenta de servicio con el rol de usuario de Video Stitcher: OAUTH_TOKEN Obtén más información para crear tokens de OAuth de corta duración. Punto clave: El token de OAuth se puede volver a usar en varias solicitudes, siempre que no haya vencido.
Código de red	El código de red de Ad Manager para solicitar anuncios: NETWORK_CODE
ID de configuración en vivo	El ID de configuración en vivo que especificaste cuando creaste el evento de transmisión en vivo: LIVE_CONFIG_ID
Clave del activo personalizada	La clave de activo personalizado de Ad Manager que se genera durante el proceso de creación de una configuración para un evento de transmisión en vivo con la API de Video Stitcher: CUSTOM_ASSET_KEY

Punto clave: Asegúrate de que el código de red y la clave de activo personalizado sean los mismos que se generaron cuando creaste la configuración activa.

Realiza una solicitud de registro de flujo a Ad Manager

Realiza una solicitud POST al extremo de registro de flujos. A cambio, recibirás una respuesta JSON que contiene el ID de transmisión para enviar a la API de unión de videos.

extremo 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

NETWORK_CODE	Tu código de red de Google Ad Manager 360: NETWORK_CODE
CUSTOM_ASSET_KEY	El identificador personalizado asociado a este evento en Google Ad Manager: CUSTOM_ASSET_KEY

Parámetros de cuerpo con codificación de formulario

Es un conjunto opcional de parámetros de segmentación codificados en formularios .

Respuesta JSON

media_verification_url	Es la URL base para enviar un ping a los eventos de seguimiento de reproducción. Para obtener una URL de verificación de medios completa, se debe adjuntar un ID de evento de anuncio a esta URL base. MEDIA_VERIFICATION_URL
metadata_url	Es la URL para solicitar los metadatos del grupo de anuncios. METADATA_URL
polling_frequency	la frecuencia recomendada en milisegundos para sondear la "metadata_url". POLLING_FREQUENCY
stream_id	Es la cadena que se usa para identificar la sesión de transmisión actual. STREAM_ID
valid_for	Es la cantidad de tiempo que queda hasta que vence 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	Es la hora a la que vence la sesión de transmisión actual, como una cadena 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 \
     -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 errores, se muestran códigos de error HTTP estándar sin cuerpo de respuesta JSON.

Analiza la respuesta JSON y almacena los valores relevantes.

Sugerencia: Las URLs proporcionadas en la respuesta de la API están sujetas a cambios sin previo aviso. Por lo tanto, usa las URLs como se proporcionan en la respuesta de la API en lugar de crearlas por tu cuenta. Esto ayuda a garantizar que tu código siga funcionando correctamente cuando cambien las URLs.

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

Realiza una solicitud POST al extremo /livesessions de la API de Video Stitcher para crear una sesión en vivo nueva. A cambio, recibes una respuesta JSON que contiene el manifiesto de transmisión para cargar en tu reproductor de video.

extremo 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

PROJECT_NUMBER	El número de proyecto del proyecto de Google Cloud que usa la API de Video Stitcher: PROJECT_NUMBER
LOCATION	La región de Google Cloud en la que se creó tu configuración activa: LOCATION

Parámetro de encabezado de autorización

OAUTH_TOKEN

El token de OAuth de corta duración de una cuenta de servicio con el rol de usuario de Video Stitcher: OAUTH_TOKEN

Parámetros de cuerpo codificados en JSON

liveConfig	Una cadena que contiene el número de proyecto, la ubicación y el ID de configuración en vivo con el siguiente formato: projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
adTracking	Configúralo como "CLIENT" para habilitar el seguimiento del cliente.
gamSettings	Un objeto que contiene el ID de transmisión con el siguiente formato: {"streamId":"STREAM_ID"}

Respuesta JSON

name	Es el nombre de la sesión en vivo, que contiene el ID de la sesión.
playUri	Es el URI del manifiesto de transmisión combinada que se cargará en tu reproductor de video para la reproducción. PLAY_URI
liveConfig	La misma cadena liveConfig que se envió a la API en el cuerpo de tu solicitud
gamSettings	El mismo objeto gamSettings que se envió a la API en el cuerpo de tu solicitud

Ejemplo de solicitud (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"
  }
}

Ejemplo de respuesta

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

Después de recibir la respuesta, puedes reproducir la transmisión en vivo con anuncios integrados haciendo referencia al URI de reproducción de la sesión del campo playUri del objeto de respuesta.

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

Una sesión inactiva vence después de 5 minutos. Una sesión se considera inactiva si no se recuperaron manifiestos durante un período determinado.

Cómo sondear metadatos de AdBreak nuevos

La aplicación es responsable de recuperar los metadatos de cada pausa publicitaria para saber qué impresiones se deben activar. Para ello, establecerás un temporizador para sondear con frecuencia las APIs de DAI metadata_url en busca de información de anuncios nueva. El intervalo de sondeo se especifica en el campo polling_frequency de la respuesta de registro del flujo.

Importante: No generes la URL de solicitud de metadatos por tu cuenta, ya que el formato está sujeto a cambios sin notificación. En su lugar, usa el valor metadata_url que se muestra en la solicitud de registro de transmisión.

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

tags	Es un conjunto de pares clave-valor que describen los eventos de contenido multimedia del anuncio que ocurrirán en la transmisión. Cada clave consta de los primeros 17 caracteres de un ID de contenido multimedia de anuncios que aparecerá en los metadatos ID3 del flujo o, en el caso de los eventos "progress", el ID de contenido multimedia de anuncios completo. Cada valor es un objeto con las siguientes propiedades: ad: Es el ID del anuncio que contiene el evento de contenido multimedia del anuncio. ad_break_id: Es el ID de la pausa publicitaria que contiene el evento de contenido multimedia del anuncio. type: Es el tipo de evento de contenido multimedia del anuncio. Los valores son uno de los siguientes: start: El anuncio comenzó. firstquartile: El anuncio está completo en un 25%. midpoint: El anuncio está completo en un 50%. thirdquartile: El anuncio está completo en un 75%. complete: El anuncio finalizó. progress: Se activa cada segundo mientras se reproduce un anuncio.
ads	Es un conjunto de pares clave-valor que describen los anuncios que aparecerán en el flujo. Cada clave es un ID de anuncio. Cada valor es un objeto con las siguientes propiedades: ad_break_id: Es el ID de la pausa publicitaria que contiene el evento de contenido multimedia del anuncio. position: Es la posición del anuncio dentro de la pausa publicitaria. Ten en cuenta que el primer anuncio de una pausa tiene una posición de 1. duration: Es la duración del anuncio en segundos de punto flotante. title: Es el título del anuncio, como se define en el archivo VAST. description: Es la descripción del anuncio, como se define en VAST. ad_system: El sistema de anuncios, como se define en VAST. ad_system: El ID del anuncio, como se define en VAST. ad_system: El ID de la creatividad, como se define en VAST. clickthrough_url: Es la URL que se abrirá cuando un usuario interactúe con el anuncio. universal_ad_id: Es un objeto que representa el ID de anuncio universal, como se define en VAST.
ad_breaks	Es un conjunto de pares clave-valor que describen las pausas publicitarias que se producirán en la transmisión. Cada clave es un ID de pausa publicitaria. Cada valor es un objeto con las siguientes propiedades: type: Es el tipo de pausa publicitaria. Los valores serán uno de los siguientes: pre: Representa un anuncio previo al video. mid: Representa un anuncio durante el video. post: Representa un anuncio al final del video. duration: Es la duración de la pausa publicitaria en segundos de punto flotante. expected_duration: Es la duración esperada de la pausa publicitaria en segundos de punto flotante. ads: Es la cantidad de anuncios que contiene la pausa publicitaria.

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

Ejemplo de solicitud (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
      },
      ...
   }
}

Escucha eventos ID3 y realiza un seguimiento de los eventos de reproducción

Para verificar que se hayan producido eventos específicos en una transmisión de video por Internet, sigue estos pasos para controlar los eventos ID3:

1. Almacena los eventos multimedia en una fila y guarda cada ID de contenido 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 establecida (se recomiendan 500 ms), compara las marcas de tiempo de los eventos con el cabezal de reproducción para verificar si hay eventos reproducidos recientemente en la cola de eventos multimedia.
3. En el caso de los eventos multimedia que confirmas que se reprodujeron, busca el ID de contenido multimedia en las etiquetas de pausas publicitarias almacenadas para verificar el tipo. Ten en cuenta que el objeto de etiquetas de pausas publicitarias solo contiene una versión truncada del ID de contenido multimedia, limitada a los primeros 10 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 en el objeto de etiquetas. Esto se hace para evitar 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 medios completa de un evento de anuncio, agrega el ID completo del evento de anuncio al valor de media_verification_url de la respuesta de creación de la transmisión.
4. Usa los eventos de "progreso" para hacer un seguimiento de si un usuario se encuentra en una pausa publicitaria. No envíes estos eventos al extremo de verificación de contenido multimedia para evitar un código de error HTTP. Para otros tipos de eventos, agrega el ID de medios a la URL de verificación de medios y realiza una solicitud GET para hacer un seguimiento de la reproducción.
5. Quita el evento multimedia de la fila.

extremo de API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parámetros de ruta

MEDIA_VERIFICATION_URL	El valor que muestra el extremo de registro de flujo, en el campo media_verification_url: MEDIA_VERIFICATION_URL
AD_MEDIA_ID	El ID de contenido multimedia de anuncios completo, tal como aparece en los metadatos ID3 de la transmisión: AD_MEDIA_ID

Valores esperados

HTTP/1.1 204 No Content	Respuesta vacía correcta.
HTTP/1.1 404 Not Found	No se reconoció el ID de verificación de contenido multimedia.
HTTP/1.1 409 Conflict	Ya se envió el ID de verificación de contenido multimedia.

Ejemplo de solicitud (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 con respecto a la segmentación:

• UserAgent: El parámetro de usuario-agente se pasa como un valor específico del navegador en lugar de la plataforma subyacente.
• rdid, idtype, is_lat: No se pasa correctamente el ID de dispositivo, lo que limita la funcionalidad de las siguientes funciones:
  • Limitación de frecuencia
  • Rotación de anuncios secuencial
  • Segmentación y segmentación por público