Cómo usar una integración personalizada

Antes de comenzar

Esta guía abarca solo las instrucciones de reproducción en ausencia del SDK de IMA de DAI.

Asegúrate de haber completado los pasos Integra Google Ad Manager (GAM) en las transmisiones en vivo de antemano.

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í sola.

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

Ubicación	El Región de Google Cloud donde 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 OAuth	El token de OAuth de corta duración de una cuenta de servicio con el usuario de Video Stitcher rol: 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	Este es el ID de la configuración en vivo que especificaste cuando creaste el evento de transmisión en vivo: LIVE_CONFIG_ID
Clave del recurso personalizada	La clave del recurso personalizado de Ad Manager que se generó durante el proceso de crear 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, recibes Una respuesta JSON que contiene el ID de transmisión para enviar a la API de Video JOIN.

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 codificados en formulario

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

Respuesta JSON

media_verification_url	La URL base para hacer ping a eventos de seguimiento de reproducción. Una verificación de medios completa La URL se forma al agregar un ID del evento del 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.

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 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 proporciona en la respuesta de la API, en lugar de construirlos tú mismo. 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 JOIN para hacer lo siguiente: crea una nueva sesión en vivo. A cambio, recibirás una respuesta JSON que contiene el manifiesto de la transmisión para cargarlo en el 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 del proyecto de Google Cloud que usa Video Stitcher API: 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 usuario de Video Stitcher rol: OAUTH_TOKEN

Parámetros del cuerpo con codificación JSON

liveConfig	Es 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 lo 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

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

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 unida con anuncios: haciendo referencia al URI de reproducción de sesión del campo playUri de la objeto de respuesta.

La API de Video Stitcher genera un ID de sesión único para Cada solicitud, que se puede recuperar desde 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.

Encuesta para metadatos nuevos de AdBreak

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 es sujeto a cambios sin previo aviso. En su lugar, usa el valor metadata_url. que devuelve la solicitud de registro de transmisión.

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

tags	Un conjunto de pares clave-valor que describen los eventos multimedia de anuncios que ocurrirán dentro de 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 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 anuncio. evento multimedia. 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	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 evento de contenido multimedia del anuncio. position: Es la posición del anuncio dentro de la pausa publicitaria. tenga en cuenta que el primer anuncio en 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: 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: Un objeto que representa el alcance el ID del anuncio, tal como se define en la plantilla 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 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 del anuncio. la interrupción 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 temporizados dentro tu transmisión de video por Internet.

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

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. Almacenar los eventos multimedia en una cola y guardar cada ID de contenido multimedia junto con sus marca de tiempo, si el jugador la 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 las etiquetas de las pausas publicitarias El objeto solo contiene una versión truncada del ID de contenido multimedia, limitada al 10 dígitos después del prefijo google_, por lo que no hay una coincidencia directa entre los IDs de verificación de medios ID3 y las claves en el objeto tags. 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 “progreso” eventos para hacer un seguimiento de si un usuario está dentro de 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 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 medios.

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 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 y segmentación por público