Esta página se ha movido; se le dirigirá a la nueva ubicacion en 3 segundos. ¡Actualiza tus marcadores!

API de configuración de anuncios SSAI de Video Cloud

En este tema, aprenderá a usar la API de inserción de anuncios del lado del servidor (SSAI) para crear y administrar configuraciones de anuncios.

Las configuraciones de anuncios definen varios aspectos de la reproducción de SSAI, incluidas las llamadas de anuncios, balizas y otras opciones de configuración. Una cuenta puede tener varias configuraciones y las configuraciones actuales no se pueden compartir entre cuentas.

información general

La siguiente información pertenece a todas las solicitudes de API SSAI.

URL base

La URL base de la API SSAI es:

https://ssai.api.brightcove.com/v1

Ruta de la cuenta

En todos los casos, las solicitudes se realizarán para un Video Cloud Cuenta. Por lo tanto, siempre agregarás el término accounts seguido del ID de tu cuenta a la URL base:

https://ssai.api.brightcove.com/v1/accounts/your account id

Autenticación

La autenticación para solicitudes requiere un encabezado de autorización:

Authorization: Bearer your access token

access_token Es un token de acceso temporal de OAuth2 que debe obtenerse del servicio OAuth de Brightcove. Para obtener detalles sobre cómo obtener credenciales de cliente y usarlas para recuperar tokens de acceso, consulte la Descripción general de Brightcove OAuth.

Operaciones

Cuando solicite credenciales de cliente, tendrá que especificar el tipo de acceso a la cuenta u operaciones que desea. La siguiente es una lista de las operaciones admitidas actualmente para la API SSAI:

  • Datos SSAI:

    video-cloud/ssai/read
    video-cloud/ssai/all

Administrar configuraciones de anuncios

La API admite las siguientes solicitudes GET y PUT:

Lista de configuraciones de anuncios

Enumere las configuraciones de anuncios definidas para una cuenta.

Método OBTENER
URL https://ssai.api.brightcove.com/v1/accounts/el id de tu cuenta/ssai_configs
Encabezados Autorización: Portador tu token de acceso
Tipo de contenido: application/json

Respuesta de muestra:

[
  {
    "name": "VMAP Ad Server",
    "vmap_response_namespace": "bc",
    "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
    "account_id": "57838016001",
    "created_timestamp": "2017-07-24T19:28:34.976878586Z",
    "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
    "ad_config": {
      "expected_ad_response": "dfp_ad_rules",
      "disable_server_beacons": false,
      "template_url": {
          "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
      }
    }
  }
]

Crea una configuración de anuncios

Cree una configuración de anuncios para una cuenta.

Método PUBLICACIÓN
URL https://ssai.api.brightcove.com/v1/accounts/el id de tu cuenta/ssai_configs
Encabezados Autorización: Portador tu token de acceso
Tipo de contenido: application/json

Cuerpo de muestra:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_config": {
  	"expected_ad_response": "vast_3_0",
  	"disable_server_beacons": false,
    "round_up_cue_points": false,
  	"template_url": {
  		"template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
  	}
  },
  "discontinuities": {
    "hls": [ "*" ]
  }
}

Obtener detalles de configuración de anuncios

Para una cuenta, obtenga los detalles de configuración de anuncios por config Id.

Método OBTENER
URL https://ssai.api.brightcove.com/v1/accounts/tu ID de cuenta/ssai_configs/tu id de configuración de anuncios
Encabezados Autorización: Portador tu token de acceso
Tipo de contenido: application/json

Respuesta de muestra:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
  "account_id": "57838016001",
  "created_timestamp": "2017-07-24T19:28:34.976878586Z",
  "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
  "ad_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
        "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  },
  "beacon_templates": [
      {
        "type": "content_start",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "content_midpoint",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "ad_start",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      },
      {
        "type": "content_complete",
        "template_url": {
          "template": "https://myserver.com/beaconRX/{{metadata.video_id}}/load?position=load&sid={{system.xfp.unique_user_id}}&jid={{metadata.video_id}}&rnd32={{sytem.random_number_32}}&bid={{system.uuid}}&t={{system.timestamp_utc}}&ua={{system.user_agent}}&ip={{system.ip_address}}&ref={{system.referer}}"
        }
      }
    ],
    "discontinuities": {
      "dash": [
        "*"
      ],
      "hls": [
        "*"
      ]
    },
    "extend_beacon_guard_ttl": true
  }
}

Actualizar una configuración de anuncios

Actualice la configuración de un anuncio por Id. De configuración.

Método PONER
URL https://ssai.api.brightcove.com/v1/accounts/tu ID de cuenta/ssai_configs/tu id de configuración de anuncios
Encabezados Autorización: Portador tu token de acceso
Tipo de contenido: application/json
Cuerpo de muestra 
{
    "name": "VMAP Ad Server - updated"
}

Respuesta de muestra:

{
  "name": "VMAP Ad Server - updated",
  "vmap_response_namespace": "bc",
  "config_id": "2ecc6beb-d6a4-4deb-a78e-37ac27e0f883",
  "account_id": "57838016001",
  "created_timestamp": "2017-07-24T19:28:34.976878586Z",
  "updated_timestamp": "2017-07-24T19:28:34.976878586Z",
  "ad_config": {
    "expected_ad_response": "dfp_ad_rules",
    "disable_server_beacons": false,
    "template_url": {
      "template": "http://solutions.brightcove.com/bcls/ads/simple-ad-rules?ip={{ system.ip_address }}&vid={{ metadata.video_id }}&ppid={{ system.unique_user_id }}&p_vmap={{ url.p_vmap }}"
    }
  }
}

Detalles del campo de configuración

Esta tabla define los campos de configuración de anuncios que se utilizan en la sección del cuerpo de una solicitud.

Campo Tipo Descripción
name cuerda Nombre legible por humanos
vmap_response_namespace cuerda Ajusta la salida de VMAP para usar el formato de espacio de nombres Unicorn Once heredado o para usar el nuevo formato de espacio de nombres de Brightcove.

Valores: uo , bc Defecto: bc
description cuerda Descripción legible por humanos
ad_config.expected_ad_response cuerda Qué tecnología usar para analizar la respuesta. [1]

Valores:
  • dfp_ad_rules
  • dfp_vmap
  • smart_xml
  • vast_3_0
ad_config.disable_server_beacons booleano Indica si se debe deshabilitar la activación del lado del servidor de impresiones de anuncios / balizas

Cuando se establece en true , SSAI no activará ninguna baliza del lado del servidor e incluirá todas las balizas en la salida VMAP

Cuando se establece en false , SSAI activará las balizas que pueda en el lado del servidor e incluirá las que no pueda en la salida de VMAP
ad_config.round_up_cue_points booleano Indica si se redondea al siguiente fotograma clave al elegir una posición cercana para insertar anuncios.

Defecto: false , que elige el fotograma clave más cercano a la posición deseada del anuncio.
ad_config.template_url.template cuerda Plantilla de etiqueta publicitaria. Variables disponibles descritas en una sección posterior.
ad_config.template_url.defaults Objeto Mapa de cadena a cadena que define el valor predeterminado para usar en el caso de que no se proporcione un parámetro de URL.

Puede ser literal { "url.foo": "SomeString" }

O hacer referencia a otra variable { "url.foo": "{{ metadata.title_id }}" }
discontinuities.dash [2] []Cuerda Controla qué versiones de tablero entregar manifiestos de tablero de períodos múltiples.

Ajustado a ["*"] para ofrecer un guión de varios períodos para todas las versiones

Lista vacía para nunca

Ejemplo: ["live-timeline"] para entregar para línea de tiempo en vivo pero no para hbbtv
discontinuities.hls [2] []Cuerda Controla qué versiones de hls entregar con discontinuidades.

Ajustado a ["*"] a la entrega con discontinuidades en todas las versiones de HLS

Lista vacía para nunca

Ejemplo: ["v4","v5"] para entregar para v4 y v5 pero no para v3
beacon_templates Matriz Una serie de balizas para disparar (ejemplo: balizas de terceros)
beacon_templates[].type cuerda

Tipo de baliza para disparar. Valores:

  • content_start
  • content_first_quartile
  • content_midpoint
  • content_third_quartile
  • content_complete
  • content_quartiles
  • content_interval
  • ad_start
  • ad_first_quartile
  • ad_midpoint
  • ad_third_quartile
  • ad_complete
  • ad_quartiles
  • ad_break_start
  • ad_break_end
  • segment_start
  • segment_end
  • on_load
beacon_templates[].template_url.template cuerda Plantilla de URL de baliza
extend_beacon_guard_ttl booleano Establece la duración del TTL (tiempo de vida) de Beacon Guard a la duración del TTL de la sesión del contenido. De lo contrario, el valor predeterminado es 1 minuto.

Variables publicitarias

Las variables de la URL de la plantilla se identifican mediante llaves dobles ({{ … }}) con espacios en blanco opcionales antes y después de la ruta de la variable. Todas las variables tienen como prefijo uno de los tres espacios de nombres:

Variables del sistema

Las variables del sistema son proporcionadas por el sistema SSAI y pueden ser información sobre el usuario final o variables auxiliares para generar valores aleatorios. Los valores deben estar codificados en URI antes de insertarse en las plantillas de URL.

Las variables del sistema se identifican como: {{system.*}}

Campo Descripción
ip_address Dirección IP del usuario final
random_number_32 Entero aleatorio de 32 bits
random_guid UUID aleatorio
referer Valor del encabezado Referer del usuario final
timestamp_utc Hora actual como marca de tiempo de Unix
unique_user_id MD5 (dirección_ip + agente_usuario)
unix_timestamp Hora actual como marca de tiempo de Unix (segundos)
user_agent Valor del encabezado del agente de usuario del usuario final
uuid Uuid aleatorio
x_forwarded_for Valor del encabezado X-Fordered-For del usuario final
xfp.correlator Entero aleatorio de 64 bits
xfp.ip_address Dirección IP del usuario final
xfp.unique_user_id MD5 (dirección_ip + agente_usuario)
xfp.scor Entero aleatorio de 64 bits

Variables de URL

Los parámetros de consulta proporcionados en el punto de entrada VMAP / Manifiesto están disponibles en el url espacio de nombres. A diferencia de las variables en otros espacios de nombres, estos parámetros no están codificados en URL cuando se insertan en la plantilla. Si los valores de las variables deben codificarse en URL que van al proveedor de anuncios, deberán codificarse en URL doble en la URL del punto de entrada.

Las variables de URL se identifican como: {{url.*}}

Variables de metadatos

Las variables de metadatos son aquellas que describen el contenido del video, derivadas de las fuentes de datos de Video Cloud y Dynamic Delivery. Los valores se codifican en URL antes de insertarse en las plantillas de URL.

Las variables de metadatos se identifican como: {{metadata.*}}

Campo Descripción
ad_keys Cadena de texto de formato libre que se puede agregar y editar en el módulo de medios de Video Cloud Studio
custom_fields.{field_name} Campos personalizados de Video Cloud
long_description Descripción detallada de Video Cloud
name Nombre del video de Video Cloud
reference_id ID de referencia de Video Cloud
tags Lista separada por comas de las etiquetas de Video Cloud para el video
title.duration Duración del contenido en segundos
title.id ID de título de Dynamic Delivery
title.name Nombre del título de Dynamic Delivery
video_id ID de video de Video Cloud
Otros pares clave / valor de Video Cloud también estarían aquí

Parámetros de URL de punto de entrada

Hay un puñado de parámetros de consulta que se pueden agregar a la URL del punto de entrada SSAI (VMAP o manifiesto) para modificar algunos comportamientos:

Parámetro Descripción
?rule=sd-only Filtra cualquier reproducción de video que tenga una altura menor que el umbral establecido en la Configuración de la cuenta
?rule=discos-enabled Habilite la reproducción con discontinuidades en HLS y MultiPeriods en Dash. Tiene prioridad sobre la configuración de discontinuidades en Playback Config
?rule=discos-disabled Deshabilite la reproducción con discontinuidades en HLS y múltiples períodos en Dash. Tiene prioridad sobre la configuración de discontinuidades en Playback Config

Notas de configuración

  1. La precarga de anuncios no debe realizarse con SSAI. La razón de esto es que si carga previamente, el reproductor informará una impresión de anuncio y probablemente las balizas del primer cuartil antes de que se reproduzca el video. Esto podría dar lugar a análisis de anuncios inexactos. Si configura SSAI en Studio, esto se hará automáticamente, pero si configura SSAI manualmente, debe tener en cuenta este problema.
  2. Si el reproductor web usa SSAI, y una de sus motivaciones para hacerlo es evitar los bloqueadores de anuncios, debe usar balizas del lado del servidor. Las balizas del lado del cliente no deben usarse ya que estarán bloqueadas.

Macros del lado del cliente

Utilizar el page prefijo cuando desee utilizar macros de anuncios del lado del cliente. Estas macros le permiten utilizar variables en VMAP y en las URL del servidor. Para obtener más información sobre la macro de anuncios, consulte las macros de anuncios y la sección ServerURL del documento Publicidad con el complemento IMA3.

Las macros del lado del cliente tienen el prefijo: {{page.*}}

Por ejemplo, para agregar el document.referrer y un pageVariable Variable de ventana DOM, los antepondría con page en la plantilla de anuncio de la siguiente manera:

https://adserver.com/{{page.document.referrer}}/{{page.pageVariable.whateverIwant}}

Vuelve la API de reproducción document.referrer y pageVariable.whateverIwant adjunto a las URL de VMAP y SRC. El reproductor de Brightcove luego ejecuta su lógica de reemplazo de macros del lado del cliente para reemplazar los valores apropiados, antes de enviar la solicitud:

https://bolt-prefix/blah.vmap?document.referrer={document.referrer}&pageVariable.whateverIwant={pageVariable.whateverIwant}

Balizas de error de anuncios

Las balizas de error de anuncios de VAST cuando se usa SSAI pueden ser útiles para encontrar y solucionar problemas de manera proactiva con el flujo de trabajo de sus anuncios. Para obtener más detalles, consulte la Balizas de error de anuncios con SSAI documento.