Resumen: API de audiencia
Referencia de API
Consulte también la Referencia de API.
URL base
La URL base para la API de audiencia es:
https://audience.api.brightcove.com/v1
Ruta de la cuenta
En todos los casos, se solicitarán una cuenta de Video Cloud específica. Siempre tendrás que añadir el término «cuentas» seguido de tu ID de cuenta a la URL base:
https://audience.api.brightcove.com/v1/accounts/{account_id}
Autenticación
La API de audiencia utiliza el servicio OAuth de Brightcove para autenticar llamadas.
Primero deberá obtener las credenciales de cliente (a y).client_id
client_secret
Se trata de una operación única que se puede realizar mediante la interfaz de usuario de credenciales de OAuth. Necesitará permisos para las operaciones de audiencia/lectura:

Puede obtener las credenciales de cliente directamente desde el servicio OAuth de Brightcove mediante cURL o Postman.
También necesitará un, que se obtiene usando el y y se pasa en un encabezado de autorización con su solicitud de API:access_token
client_id
client_secret
Authorization: Bearer {access_token}
El caduca después de cinco minutos, por lo que debe obtener uno para cada solicitud, o comprobar para asegurarse de que su token sigue siendo válido.access_token
Consulte Obtención de tokens de acceso para obtener una explicación detallada de cómo obtener tokens de acceso, incluidos ejemplos de código.
Tratamiento de errores
Si se produce 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:
Código de Estado | Código de error | Descripción |
---|---|---|
400 | ERROR BAD_REQUEST_ | Los parámetros de consulta no son válidos |
401 | UNAUTHORIZED_ERROR | El token de acceso está ausente, ha caducado o no es válido |
404 | RESOURCE_NOT_FOUND | La URL no existe |
429 | REQUEST_THROTTLED_ERROR | El usuario ha superado la política de limitación de velocidad |
500 | INTERNAL_ERROR | Se ha producido un error interno |
504 | GATEWAY_TIMEOUT_ERROR | El tiempo de espera del servidor se agotó mientras cumplía su solicitud |
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 ORs lógicas y punto y coma 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 = prueba».
Selección de campos para devolver
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.
Rango de fechas
Los intervalos de fechas se pueden especificar en from
y to
parámetros y se aplican a la fecha en la que se actualizó por última vez el evento de vista (el campo updated_at). Los intervalos de fechas se pueden indicar en los siguientes formatos:
- El valor de 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, como2013-09-12
. Para las fechas expresadas en este formato:- Cualquier intervalo de fechas especificado se interpretará en UTC
- La hora para la fecha de entrega será interpretada como medianoche (
00:00:00
) en la fecha especificada
- Fechas relativas: puede expresar cualquiera de las
to
yfrom
valores relativos al otro end
(dias),h
(horas),m
(minutos), os
(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 elementos a devolver (predeterminado: 25; máximo: 100). offset
es el número de elementos a omitir (predeterminado: 0). Puedes usar y juntos para crear una aplicación que pagina a través de los resultados.limit
offset
Cada uno incluye limit
, offset
, y count.
, que puede utilizar para configurar la iteración sobre los resultados totales. Por ejemplo, en JavaScript, puede obtener el total de iteraciones 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 vista 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 ejemplo 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}"
La respuesta se verá así:
{
"count": 27,
"limit": 25,
"offset": 0,
"result": [
{
"created_at": "2016-04-25T18:30:21.651Z",
"page_url": "http://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": "http://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 para filtrado y selección
Todos los parámetros se pueden utilizar con view_event
solicitudes.
Aquí hay una solicitud de ejemplo 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 se admiten para view_event
las solicitudes al filtrar con una where
cláusula o al seleccionar durante una fields
cláusula:
Campo | Descripción |
---|---|
video_id: | ID de vídeo de Brightcove |
video_name: | Nombre del vídeo de Brightcove |
id_rastreo | ID de seguimiento personalizado |
external_id | El Marketo, Eloqua o GUID personalizado |
id_player_ | El ID del reproductor de Brightcove que creó el evento de vista |
page_url | La dirección URL de la página donde se creó el evento de vista |
vistos | Porcentaje observado |
time_watched | Segundos del vídeo visto |
created_at | Fecha de creación |
updated_at | Fecha de última actualización |
is_synced | Un booleano que indica si el evento de vista se ha sincronizado o no |
evento_1 | Eventos personalizados |
evento_2 | |
evento_3 | |
métric_1 | Métricas personalizadas |
métric_2 | |
métric_3 |
Recuperando clientes potenciales
Para recuperar eventos de vista en una cuenta, realice una GET
solicitud al view_events
recurso:
https://audience.api.brightcove.com/v1/accounts/{account_id}/leads
Respuesta de muestra:
{
"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": "http://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": "http://players.brightcove.net/1486906377/Hk4TBqzL_default/index.html?videoId=4997275041001",
"player_id": "Hk4TBqzL",
"video_id": "4997275041001"
}
]
}
Campos para filtrado y selección
Todos los parámetros se pueden utilizar con leads
solicitudes.
Aquí hay una solicitud de ejemplo 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 se admiten para leads
las solicitudes al filtrar con una where
cláusula o al seleccionar durante una fields
cláusula:
Campo | Descripción |
---|---|
video_id: | ID de vídeo de Brightcove |
external_id | El Marketo, Eloqua o GUID personalizado |
id_player_ | El ID del reproductor de Brightcove que creó el evento de vista |
page_url | La dirección URL de la página donde se creó el evento de vista |
created_at | Fecha de creación |
dirección de correo electrónico | La dirección de correo electrónico del cliente potencial |
nombre_nombre | El nombre del plomo, si se proporciona |
apellidos | El apellido del plomo, si se proporciona |
Business_phone | El número de teléfono del cliente potencial si se proporciona |
país | El país del plomo si se proporciona |
nombre_empresa | La compañía del plomo si se proporciona |
industria | La industria a la que pertenece el plomo si se proporciona |