API de Video Cloud SSAI

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 Autenticación para solicitudes de API de Brightcove.

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
• Crea una configuración de anuncios
• Obtener detalles de configuración de anuncios
• Actualizar una configuración de anuncios

Lista de configuraciones de anuncios

Enumere las configuraciones de anuncios definidas para una cuenta.

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": "https://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 }}"
      }
    }
  }
]

Para ver las definiciones de los campos, consulte la sección Detalles del campo Configuración .

Crea una configuración de anuncios

Cree una configuración de anuncios para una cuenta.

Cuerpo de muestra:

{
  "name": "VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "ad_tracking_sample_percentage": 100,
  "ad_config": {
    "expected_ad_response": "vast_3_0",
    "disable_server_beacons": false,
    "round_up_cue_points": false,
    "template_url": {
      "template": "https://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": [ "*" ]
  }
}

Para ver las definiciones de los campos, consulte la sección Detalles del campo Configuración .

Notas

• ad_tracking_sample_percentage determina el porcentaje de sesiones que se registrarán. Puede tener cualquier valor desde 0 (deshabilitar el registro) hasta 100 (registrar todas las sesiones).

Obtener detalles de configuración de anuncios

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

	{
		"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_tracking_sample_percentage": 100,
		"ad_config": {
			"expected_ad_response": "dfp_ad_rules",
			"disable_server_beacons": false,
			"template_url": {
					"template": "https://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
		}
	}

Para ver las definiciones de los campos, consulte la sección Detalles del campo Configuración .

Actualizar una configuración de anuncios

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

{
    "name": "VMAP Ad Server - updated"
}

	{
		"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": "https://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 }}"
			}
		}
	}

Para ver las definiciones de los campos, consulte la sección Detalles del campo Configuración .

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.

Tipos de respuesta de anuncios

Aquí hay información adicional sobre cómo trabajar con ad_config.expected_ad_response tipos de la tabla anterior. Valores:

• vast_3_0- Plantilla de publicación de anuncios de video digital (VAST)
• dfp_vmap- Lista de reproducción de anuncios múltiples de video (VMAP)
• dfp_ad_rules- Formato propietario de Google DFP, que se ha renombrado como Google Ad Manager (GAM)
• smart_xml- Formato propietario para FreeWheel

Flujo del proceso

Al crear configuraciones de anuncios SSAI, tenga en cuenta las siguientes notas de proceso:

VMAP

Si el tipo de respuesta de anuncio de SSAI Config es DFP VMAP:

• Se ignorarán todos los puntos de referencia configurados con un video.
• SSAI analiza el archivo XML VMAP del proveedor de anuncios que contiene todos los anuncios con sus posiciones definidas.

VASTO

Si el tipo de respuesta de anuncios de SSAI Config es VAST 3.0:

• Defina puntos de referencia en su video. SSAI realizará solicitudes para cada punto de referencia en el video para construir pausas publicitarias.
• Si no se configura ningún punto de referencia con un video, se inserta un anuncio pre-roll de forma predeterminada.

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:

• sistema
• url
• metadatos

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

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

Las variables de URL deben reemplazarse mediante la integración personalizada de la siguiente manera:

1. Escriba código para realizar una solicitud a la API de reproducción.
2. Interceptar los datos devueltos por la solicitud de la API.
3. Reemplace cualquier {{url.*}} tokens en las URL de origen
4. Cargue los datos/la fuente en el reproductor (Brightcove Player para web o los SDK nativos)

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 (excepto por ad_keys) se codifican como URL antes de insertarse en las plantillas de URL.

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

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:

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.