Cómo usar una integración personalizada

Antes de comenzar

En este documento, 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 los activos de VOD 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 verificaciones de medios 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 de VOD	El ID de configuración de VOD que especificaste cuando creaste tu evento de transmisión de VOD: VOD_CONFIG_ID

Realiza una solicitud de registro de flujo a Ad Manager

Realiza una solicitud POST al extremo de registro de flujos. A cambio, recibes una respuesta JSON que contiene el ID de transmisión para enviar a tu servidor de manipulación de manifiestos y a los extremos de la API de Pod Serving asociados.

extremo de API

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

Parámetros de ruta

NETWORK_CODE

Tu código de red de Google Ad Manager 360

Parámetros de cuerpo codificados en JSON

targeting_parameters

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

Respuesta JSON

media_verification_url	Es la URL base para enviar un ping a los eventos de seguimiento de la 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
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/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 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 una sesión de VOD de Cloud Video Stitcher

Realiza una solicitud POST al extremo de registro de la sesión de VOD. A cambio, recibes una respuesta JSON que contiene el URI del manifiesto de transmisión y los metadatos sobre las pausas publicitarias, los anuncios y los eventos de anuncios.

extremo 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

PROJECT_NUMBER	Es el número de tu proyecto de Google Cloud.
LOCATION	Tu región de Google Cloud
NETWORK CODE	Tu código de red de Google Ad Manager 360

Parámetros de cuerpo codificados en JSON

vodConfig	Es una cadena que contiene el número de proyecto, la ubicación y el ID de configuración de VOD con el siguiente formato: projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking	Configúralo como "CLIENT" para habilitar el seguimiento del cliente.
gamSettings	Un objeto que contiene el código de red y el ID de transmisión con el siguiente formato: { "networkCode":"NETWORK_CODE", "streamId":"STREAM_ID" }

Respuesta JSON

name	Es el nombre de la sesión de VOD, 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. SESSION_PLAYBACK_URI
adTracking	Es el mismo valor de adTracking que se envió a la API en el cuerpo de tu solicitud.
vodConfig	La misma cadena vodConfig que se envió a la API en el cuerpo de la 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/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"
  }
}

Ejemplo de respuesta

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

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

Cómo solicitar metadatos de grupos de anuncios desde Ad Manager

Realiza una solicitud GET al metadata_url que recibiste cuando registraste tu transmisión con Ad Manager. Este paso debe ocurrir después de que hayas recibido el manifiesto unido del URI de reproducción.

A su vez, recibes un objeto JSON que describe las pausas publicitarias, los anuncios y los eventos de anuncios de la transmisión.

Extremo de API

GET: METADATA_URL
Host: dai.google.com

Respuesta JSON

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.

Ejemplo de solicitud (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 con eventos de metadatos cronometrados en tu transmisión de video.

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