Descripción general: API de audiencia

Referencia de API

También vea el Referencia de API.

URL base

La URL base de Audience API es:

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

Ruta de la cuenta

En todos los casos, las solicitudes se realizarán para un Video Cloud Cuenta. Siempre deberá agregar el término "cuentas" seguido de su ID de cuenta a la URL base:

https://audience.api.brightcove.com/v1/accounts/{account_id} 

Autenticación

La API Audience usa Brightcove Servicio OAuth para autenticar llamadas.

Primero deberá obtener las credenciales del cliente (un client_id y client_secret). Ésta es una operación única que se puede realizar utilizando el Interfaz de usuario de credenciales de OAuth. Necesitará permisos para las operaciones de audiencia / lectura:

Puede obtener las credenciales del cliente directamente desde Brightcove OAuth Service utilizando rizo o Cartero.

También necesitarás un access_token, que se obtiene utilizando el client_id y client_secret y se pasa un encabezado de autorización con tu solicitud de API:

Authorization: Bearer {access_token}

La access_token caduca después de cinco minutos, por lo que debe obtener uno para cada solicitud, o verificar para asegurarse de que su token aún sea válido. Ver Obtener tokens de acceso para obtener una explicación detallada de cómo obtener tokens de acceso, incluidos ejemplos de código.

Manejo de errores

Si ocurre un error, la API responderá con uno de los siguientes códigos de estado y un código de error correspondiente en el cuerpo de la respuesta:

A continuación se muestra un cuerpo de respuesta de muestra para un error:

[
	{
	"error_code": "UNAUTHORIZED_ERROR",
	"message": "Permission denied"
	}
]

Parámetros

Hay varios parámetros que puede agregar a las solicitudes para limitar y filtrar los datos recuperados. Estos se aplican a todos los tipos de solicitud descritos en las secciones siguientes.

Filtrar resultados

Puede filtrar los resultados utilizando el where parámetro. La sintaxis de los filtros es:

where=field1==value1;field2==value2

Por ejemplo:

where=video_id==123456789;video_name==test

Las comas se tratan como OR lógicos y los puntos y comas como AND lógicos. Por ejemplo, where=video_id==1234,5678;video_name=test se interpreta como "donde video_id = 1234 OR 5678, AND video_name = test".

Seleccionar campos para regresar

Se puede especificar una lista de campos en la solicitud para limitar los resultados a ese subconjunto de campos. La sintaxis de los campos es:

fields=field1,field4

Por ejemplo:

fields=video_id,video_name

Los campos que puede filtrar y ordenar se detallan para cada tipo de solicitud en las secciones siguientes.

Intervalos de fechas

Los rangos de fechas se pueden especificar en from y to y se aplican a la fecha en que se actualizó por última vez el evento de vista (el campo updated_at). Los rangos de fechas se pueden indicar en los siguientes formatos:

• El valor del texto now que representa la hora actual
• Valores de tiempo de época en milisegundos, como 1377047323000
• Fechas expresadas en formato de fecha internacional estándar ISO 8601: YYYY-MM-DD formato, como 2013-09-12. Para fechas expresadas en este formato:
  • Cualquier rango de fechas especificado se interpretará en UTC
  • La hora de la fecha indicada se interpretará como medianoche ( 00:00:00 ) en la fecha especificada
• Fechas relativas: puede expresar cualquiera de las to y from valores relativos al otro en d (dias), h (horas), m (minutos), o s (segundo). Por ejemplo:
  • from=2015-01-01&to=31d
  • from=-48h&to=now
  • from=-2d&to=now(dará los mismos resultados que el ejemplo anterior)
  • from=-365d&to=2015-12-31
  • from=-10m&to=now

Resultados de paginación

El limit es el número de artículos a devolver (predeterminado: 25; máximo: 200). offset es el número de elementos a omitir (predeterminado: 0). Puedes usar limit y offset juntos para crear una aplicación que recorra los resultados. Cada uno incluye el limit offset, y count., que puede usar para configurar iteración superior sobre los resultados totales. Por ejemplo, en JavaScript, podría obtener las iteraciones totales requeridas de esta manera:

// response is the JSON-parsed response from the first request
var totalRequests = Math.ceil(response.count / response.limit)

Recuperando eventos de vista

Para recuperar eventos de visualización en una cuenta, realice una GET solicitud al recurso view_events:

https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events

Aquí hay una solicitud de muestra en cURL

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

{
"count": 27,
"limit": 25,
"offset": 0,
"result": [
		{
				"created_at": "2016-04-25T18:30:21.651Z",
				"page_url": "https://players.brightcove.net/1486906377/V1s6NOwRx_default/index.html?videoId=4842718056001",
				"player_id": "V1s6NOwRx",
				"time_watched": 2,
				"updated_at": "2016-04-25T18:30:21.651Z",
				"video_id": "4842718056001",
				"video_name": "Horses Heading to the Track",
				"watched": 19
		},
		{
				"created_at": "2016-04-25T18:31:55.071Z",
				"page_url": "https://players.brightcove.net/1486906377/BkgFuzyhg_default/index.html?videoId=4842718056001",
				"player_id": "BkgFuzyhg",
				"time_watched": 15,
				"updated_at": "2016-04-25T18:32:00.879Z",
				"video_id": "4842718056001",
				"video_name": "Horses Heading to the Track",
				"watched": 99
		}, ...
}
]

Campos de filtrado y selección

Todos parámetros se puede utilizar con view_event peticiones.

Aquí hay una solicitud de muestra en cURL usando los parámetros:

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/view_events?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

Los siguientes campos son compatibles con view_event solicitudes al filtrar con un where cláusula o al seleccionar durante una fields cláusula:

Recuperar clientes potenciales

Para recuperar eventos de visualización en una cuenta, realice una GET solicitud a la view_events recurso:

https://audience.api.brightcove.com/v1/accounts/{account_id}/leads

{
"count": 2,
"limit": 25,
"offset": 0,
"result": [
		{
				"created_at": "2016-06-30T12:57:11.283Z",
				"email_address": "bbailey@brightcove.com",
				"first_name": "Bob",
				"last_name": "Bailey",
				"page_url": "https://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
				"player_id": "Hk4TBqzL",
				"video_id": "4997275041001"
		},
		{
				"created_at": "2016-06-30T12:57:33.301Z",
				"email_address": "rcrooks@brightcove.com",
				"first_name": "Robert",
				"last_name": "Crooks",
				"page_url": "https://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
				"player_id": "Hk4TBqzL",
				"video_id": "4997275041001"
		}
]
}

Campos de filtrado y selección

Todos parámetros se puede utilizar con leads peticiones.

Aquí hay una solicitud de muestra en cURL usando los parámetros:

curl -i https://audience.api.brightcove.com/v1/accounts/{account_id}/leads?where=video_id==123&from=-5d&to=now&sort=-created_at \
  -H "Authorization: Bearer {token}"

Los siguientes campos son compatibles con leads solicitudes al filtrar con un where cláusula o al seleccionar durante una fields cláusula: