soporte Contactar con Soporte | Estadoestado del sistema del sistema
Contenido de la página

    Resumen: API de audiencia

    En este tema, aprenderá acerca de la API de audiencia. La API de audiencia le permite recuperar datos de eventos y prospectos de visualización.

    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_idclient_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:

    Permisos necesarios
    Permisos necesarios

    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_tokenclient_idclient_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, como 2013-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 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 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.limitoffset 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