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 se encuentra disponible para la plataforma que utiliza, debe tener para llamar a las APIs necesarias y activar las verificaciones de medios de anuncios a sí mismo.

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

Ubicación	El Región de Google Cloud donde se creó la configuración activa: LOCATION
Número de proyecto	El número del proyecto de Google Cloud que usa la herramienta de unión de videos API: PROJECT_NUMBER
Token de OAuth	El token de OAuth de corta duración de una cuenta de servicio con el usuario de Video Stitcher rol: OAUTH_TOKEN Más información sobre Crear tokens 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	Este es 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 flujo para enviar a la manipulación del manifiesto y 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 del cuerpo con codificación JSON

targeting_parameters

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

Respuesta JSON

media_verification_url	La URL base para hacer ping a 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
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 venza 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	El momento en que vence la sesión de transmisión actual, como ISO 8601 string de fecha y hora en yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm de un conjunto de datos tengan un formato común.

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 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 las URLs cambian.

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 del cuerpo con codificación JSON

vodConfig	Una cadena que contiene tu número de proyecto, ubicación y ID de configuración de VOD con el siguiente formato: projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID
adTracking	Configúralo en "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	El URI del manifiesto de transmisión unido, que se cargará en tu reproductor de video para la reproducción. SESSION_PLAYBACK_URI
adTracking	El mismo valor de adTracking enviado a la API en tu solicitud cuerpo.
vodConfig	La misma cadena vodConfig enviada a la API en tu solicitud cuerpo.
gamSettings	El mismo objeto gamSettings enviado a la API en tu solicitud cuerpo.

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 te 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 del flujo.

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 un ID de medios del anuncio que aparecerá en los metadatos del ID3 de la transmisión o en el caso de los eventos "progress", el ID completo de medios del anuncio. Cada valor es un 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 anuncio. evento multimedia. type: Es el tipo de evento 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	Un conjunto de pares clave-valor que describen los anuncios que aparecerán en la en tiempo real. Cada clave es un ID de anuncio. Cada valor es un objeto con los siguientes elementos: propiedades: ad_break_id: Es el ID de la pausa publicitaria que contiene el anuncio. evento multimedia. 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 punto flotante. segundos. 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: Es el sistema de anuncios, como se define en VAST. ad_system: Es el ID del anuncio, como se define en el anuncio de VAST. ad_system: Es el ID de la creatividad, como se define en la plantilla VAST. clickthrough_url: Es la URL que se abrirá cuando un usuario interactúe con el anuncio. universal_ad_id: Un objeto que representa el alcance el ID del anuncio, tal como se define en la plantilla VAST.
ad_breaks	Un conjunto de pares clave-valor que describen las pausas publicitarias que ocurrirán dentro de 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 lo siguiente: 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 dentro de tu transmisión de video.

Escucha eventos ID3 y sigue eventos de reproducción

Para verificar que se hayan producido eventos específicos en una transmisión de video, 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 del reproductor o con una frecuencia definida (500 ms) recomendado), comprueba la cola de eventos multimedia para ver los eventos reproducidos recientemente de comparando las marcas de tiempo del evento con el cabezal de reproducción
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 es para Evitar que se envíen pings de verificación de eventos antes del evento ID3 llega. Para generar la URL completa de verificación de medios de un evento de anuncio, sigue estos pasos: agrega el ID de evento de anuncio completo al valor media_verification_url de la para crear una transmisión continua.
4. Usa los eventos "progress" 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 medios para evitar una solicitud HTTP código de error. 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 devuelve el extremo de registro de transmisión, en el Campo media_verification_url: MEDIA_VERIFICATION_URL
AD_MEDIA_ID	El ID completo de medios del anuncio, como aparece en los metadatos de 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.

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

• UserAgent: El parámetro usuario-agente se pasa como un valor específico del navegador. en lugar de en 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 de público