Descripción general: Dimensiones, campos y parámetros

Las dimensiones son las categorías de datos clave para Analytics API informes de datos Este tema proporciona una guía interactiva de las dimensiones y los campos que se pueden devolver para ellas. También muestra qué dimensiones se pueden combinar en un informe y los campos disponibles para las diferentes combinaciones.

Dimensiones y campos

Las dimensiones son los depósitos de datos principales para el análisis. Para ver guías completas de las dimensiones individuales, haga clic en el nombre de la dimensión en la lista a continuación.

Seleccione la (s) dimensión (es) a continuación para ver los campos que se pueden devolver. También puede hacer clic en el Hacer una solicitud para hacer una solicitud de muestra y ver los resultados. Si selecciona varias dimensiones incompatibles, verá un mensaje a tal efecto.

Aporte

Seleccione la (s) dimensión (es) para informar sobre:





















Campos para devolver:

 
 

(utiliza una cuenta de muestra de Brightcove)

Producción

Más temprano from fecha para esta combinación de dimensiones:  

 

Solicitud de API de muestra:

Datos de respuesta

Response will appear here...
JSON

Notas

  1. Por defecto, video_view es el único campo devuelto; los demás campos se devolverán solo si se especifican en el valor de la fields parámetro.
  2. Si especifica un campo para devolver que no es compatible con la dimensión o combinación de dimensiones, un UNSUPPORTED_FIELD_COMBINATION_ERROR se devolverá el error.
  3. La bytes_delivered El campo incluye todos los datos entregados por Video Cloud a los clientes, incluidos los datos de video, imágenes, pistas de texto y otros activos, así como el código del reproductor en sí. Algunos de estos datos se obtienen de CDN y es posible que no estén disponibles hasta por 3 días.
  4. Además de los campos que se muestran para el video dimensión, también puede devolver video.custom_fields.{field_name}

Solicitud de ejemplo

Un caso de uso típico para obtener un informe en múltiples dimensiones: desea un desglose de las vistas de video entre dispositivos de escritorio y dispositivos móviles, y también desea saber cuántas de las vistas de dispositivos móviles se realizaron en dispositivos iOS en comparación con dispositivos Android, y cuántas de los dispositivos de escritorio las vistas estaban en Macs frente a máquinas con Windows. Actualmente no hay un informe estándar en el módulo de análisis de Studio que proporcione esta información, pero puede obtenerlo a través de este Analytics API llamada:

https://analytics.api.brightcove.com/v1/data?accounts=57838016001&dimensions=video,device_type,device_os&from=2014-01-01&to=2014-04-01&fields=video_view
HTTP

(En este caso, estamos solicitando visualizaciones de video para el período comprendido entre el 1 de enero y el 1 de abril de 2014).

Ejemplo usando cURL

Si desea probar la API utilizando rizo , aquí hay un par de notas:

  • Primero necesitará obtener un token de acceso
  • Dado que la URL de la solicitud siempre incluirá parámetros de URL , deberá escribirlo entre comillas (sencillas o dobles)

Muestra

Aquí hay un comando cURL de muestra:

curl -s --header "Authorization: Bearer $ACCESS_TOKEN" \
"https://analytics.api.brightcove.com/v1/data?accounts={account_id}&dimensions=video&from=2017-04-04&limit=100"
Bash

Si reemplaza $ACCESS_TOKEN con un token de acceso válido, y {account_id} con su identificación de cuenta, esta solicitud debería funcionar. Tenga en cuenta que puede utilizar esta aplicación de muestra para generar un token de acceso.

Combinaciones de dimensiones admitidas

Para una referencia rápida, la siguiente tabla muestra combinaciones de dimensiones que son compatibles o no. Tenga en cuenta que hay algunos casos en los que se pueden utilizar más de dos dimensiones. Puedes resolverlos usando el Dimensiones y campos herramienta de arriba.

Combinaciones de dimensiones admitidas
  cuenta browser_type ciudad país fecha fecha_hora dominio_destino ruta de destino device_os device_manufacturer tipo de dispositivo live_stream jugador referrer_domain región términos_de_búsqueda plataforma_social tipo de fuente video
account n / A    
browser_type n / A                            
city   n / A                        
country   n / A                  
date n / A  
date_hour   n / A
destination_domain       n / A                    
destination_path         n / A                      
device_os         n / A              
device_manufacturer             n / A                  
device_type             n / A          
live_stream                   n / A              
player           n / A      
referrer_domain                   n / A    
region               n / A        
search_terms                       n / A    
social_platform                             n / A  
source_type                       n / A
video               n / A

Parámetros de URL

Los informes de la API de Analytics admiten los siguientes parámetros de URL.

Parámetros de URL
Parámetro Descripción Requerido Valores Predeterminado
account Las cuentas sobre las que desea informar uno o más ID de cuenta como una lista delimitada por comas ninguno
dimensions Las dimensiones sobre las que informar una o más dimensiones como una lista delimitada por comas (algunas combinaciones no son válidas; use la herramienta interactiva aquí para determinar si una combinación es válida) ninguno
where Se utiliza para especificar filtros para informes. no {dimensión}=={valor}: uno o más como una lista delimitada por punto y coma. El valor será uno o más valores para la métrica principal de esa dimensión. Por ejemplo: video==video_id , country=country-code , o viewer=viewer_id (en este último caso, la forma del viewer_id variará dependiendo de si usted mismo está capturando y enviando algún tipo de viewer_id o dependiendo del valor generado por el sistema de análisis). ninguno
limit Número de artículos a devolver no entero positivo 10
offset Número de elementos para omitir no entero positivo 0
sort Campo en el que ordenar los elementos no cualquier campo que está siendo devuelto por la solicitud video_view
fields Campos para devolver no varía según la dimensión sobre la que está informando vídeo,vista_de_video
format Formato para devolver resultados en no json (predeterminado) | CSV | xlxs json
reconciled Si se incluye, limitará los resultados a datos históricos o en tiempo real. Los datos de análisis se derivan de varias fuentes: algunos los envía el reproductor, pero otros datos se recopilan de los CDN y el sistema Video Cloud. Para entregar análisis lo más rápido posible, comenzamos a entregar datos "en tiempo real" tan pronto como estén disponibles, y luego ajustamos los análisis más tarde cuando los datos de todas las fuentes se han recopilado y procesado. Los datos totalmente procesados se denominan reconciliados. no verdadero | falso verdadero
from El comienzo del rango de fechas para la solicitud no Uno de los siguientes:
  • Una fecha ISO 8601 (AAAA-MM-DD)
  • Tiempo de época en milisegundos (ejemplo: 1659641316719 [= jueves, 4 de agosto de 2022 7:28:36.719 p. m. GMT]). Ver el convertidor de tiempo de Epoch.
  • Una cuerda: from=alltime
  • +/- fechas relativas en días (d), semanas (w) o meses (m) - ejemplo: from=-6m&to=%2B2w (el período desde hace 6 meses hasta 2 semanas después de eso; tenga en cuenta que el signo + debe codificarse como URI %2B)

Solo se permiten las fechas dentro de los últimos 32 días para los puntos de finalización del compromiso o si se concilian = false.

-30d
to El final del rango de fechas para la solicitud no Uno de los siguientes:
  • Una fecha ISO 8601 (AAAA-MM-DD)
  • Tiempo de época en milisegundos (ejemplo: 1659641316719 [= jueves, 4 de agosto de 2022 7:28:36.719 p. m. GMT]). Ver el convertidor de tiempo de Epoch.
  • Una cuerda: to=now
  • +/- fechas relativas en días (d), semanas (w) o meses (m) - ejemplo: from=-6m&to=%2B2w (el período desde hace 6 meses hasta 2 semanas después de eso; tenga en cuenta que el signo + debe codificarse como URI %2B)

Solo se permiten las fechas dentro de los últimos 32 días para los puntos de finalización del compromiso o si se concilian = false.

ahora

Cuentas

Las cuentas de Video Cloud para las que desea un informe se especifican mediante el accounts parámetro. Por ejemplo:

https://analytics.api.brightcove.com/v1/data?accounts={account1_id,account2_id}
HTTP

Donde filtros

La sintaxis general de los filtros es:

where=dimension1==value1;dimension2==value2
HTTP

Por ejemplo:

https://analytics.api.brightcove.com/v1?accounts=account_id(s)&dimensions=device_type&where=video==video_id;device_type==tablet
HTTP

Las comas se tratan como OR lógicos y los puntos y comas como AND lógicos. Por ejemplo, where=video==1234,5678;player==9876 se interpreta como "donde video = 1234 O 5678 Y jugador = 9876 "

Espacios y personajes especiales

Los valores de cadena deben estar codificados en URI. También puede escapar de los caracteres especiales usando un "":

where=search_terms==boston,%20ma
HTTP

Puede utilizar cualquier dimensión como filtro, pero solo si esa dimensión también se incluye en el dimensions estás solicitando.

Filtrado por propiedades de video

Usando el especial where=video.q=={property}:{value} filtro, puede limitar su informe a un conjunto específico de videos en función de una variedad de propiedades, que incluyen:

  • etiquetas
  • reference_id
  • Campos Personalizados [1]
  • {a_specific_custom_field}
  • created_at

Notas

[1] La sintaxis básica es where=video.q==custom_fields:value (coincide con el valor de cualquier campo personalizado) o where=video.q==myfield:value (coincide con el valor del campo personalizado específico myfield). Si está buscando en campos personalizados específicos, tenga en cuenta que debe buscar en el Nombre interno , no el nombre para mostrar:

Nombre interno vs nombre para mostrar
Nombre interno vs nombre para mostrar

Una comprobación rápida de si está utilizando el nombre correcto: el nombre interno será todo en minúsculas y sin espacios.

Ejemplos

Aquí hay algunos ejemplos where filtros para buscar etiquetas y campos personalizados:

Etiqueta única
where=video.q==tags:foo
HTTP
Varias etiquetas:
where=video.q==tags:foo,bar
HTTP
Campos Personalizados
where=video.q==custom_fields:foo
HTTP
Etiquetas y campos personalizados
where=video.q==tags:foo,bar+custom_fields:fish
HTTP

Tenga en cuenta que el video.q la función de búsqueda incluye AND , OR y NOT lógica de la siguiente manera:

  • A + El signo (más) antes del término de búsqueda significa resultados deber incluir este término.
  • A - El signo (menos) antes del término de búsqueda significa resultados no debe incluir este término.
  • Si no hay un signo más o menos, los resultados pueden incluir o no este término.

Los siguientes ejemplos ilustran el uso de esta lógica.

Ejemplos de búsqueda
where Filtrar Resultados
where=video.q==tags:red%20tags:blue%tags:green videos con las etiquetas red O blue O green Será devuelto
where=video.q==+tags:red%20tags:blue%tags:green los videos devueltos DEBEN tener la etiqueta red Y puede tener las etiquetas blue O green
where=video.q==+tags:red%20tags:blue%-tags:green los videos devueltos DEBEN tener la etiqueta red Y puede tener la etiqueta blue , pero NO debe tener la etiqueta green

Para obtener una explicación completa de esta sintaxis de consulta, consulte Usando la API de CMS: Buscar videos.

Resumen de filtros y valores permitidos

La siguiente tabla muestra los valores permitidos para cada dimensión utilizada como filtro:

Filtro de dimensión Valores permitidos
account
  • The account dimension is not used as a filter.
browser_type
  • chrome
  • edge
  • firefox
  • ie
  • opera
  • safari
  • other
city
  • A comma-delimited list of city names - e.g. Seattle,Boston,San%20Francisco
country
  • comma-delimited list of ISO-3611-1 country codes - e.g.: KO,US
date
  • The date dimension is not used as a filter.
date_hour
  • The date_hour dimension is not used as a filter.
destination_domain
  • The destination_domain dimension is not used as a filter.
destination_path
  • The destination_path dimension is not used as a filter.
device_os
  • android
  • bada
  • ios
  • rim
  • symbian
  • web_os
  • windows
  • os_x
  • mac
  • linux
  • other
device_manufacturer
  • amazon
  • apple
  • asus
  • blackberry
  • fujitsu
  • google
  • htc
  • huawei
  • kyocera
  • lenovo
  • lg
  • micromax
  • microsoft
  • nintendo
  • panasonic
  • roku
  • samsung
  • sharp
  • sony
  • vizio
  • zte
  • other
device_type
  • mobile
  • tablet
  • tv
  • desktop
  • other
live_stream
    player
    • player ids as a comma-delimited list
    referrer_domain
    • A comma-delimited list of domains; e.g. brightcove.com,docs.brightcove.com
    region
    • comma-delimited list of the ISO-3611-2 region code - e.g. US-WA
    search_terms
    • URI-encoded, comma-delimited list of search terms - e.g. players,videos
    social_platform
    • facebook
    • twitter
    • youtube
    source_type
    • direct
    • referral
    • organic_search
    • paid_search
    • secure_search
    video
    • video ids as a comma-delimited list or video.q=={video field}:{value}
    viewer
    • video ids as a comma-delimited list or video.q=={video field}:{value}

    Intervalos de fechas

    Intervalos de fechas, especificados en from y to parámetros para todo tipo de informes, se pueden indicar en diferentes formatos:

    • Valores de texto:
      • to=now(disponible y el valor predeterminado para todas las solicitudes)
    • Valores de tiempo de época en milisegundos, como 1377047323000
    • Fechas expresadas en formato de fecha internacional estándar ISO 8601: YYYY-MM-DDformato, como 2013-09-12. Para fechas expresadas en este formato:
      • Se interpretará cualquier intervalo de fechas especificado en la zona horaria establecida para la cuenta
      • La hora de la fecha indicada se interpretará como medianoche ( 00:00:00 ) en la fecha especificada en la zona horaria establecida para la cuenta
    • Fechas relativas: puede expresar cualquiera de las to y from valores relativos al otro en d (días) oh (horas). 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=2014-12-31

      Tenga en cuenta que los números negativos (-2d) se interpretan como "antes" (el otro valor) y los números positivos (48h) se tratan como "desde" (el otro valor)

    Para generar un informe sobre alguna dimensión como "video" para un solo día, configure los valores desde y hacia esa fecha:

    ...&dimensions=video&from=2013-11-01&to=2013-11-01
    HTTP

    Límite y compensación

    La limit es el número de artículos a devolver (predeterminado: 10). Para devolver todos los artículos, utilice limit=all . 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.

    Datos conciliados

    La reconciled El parámetro es un booleano. Si está configurado para true , los resultados se limitarán a los datos conciliados. Si false , los resultados se limitarán a datos en tiempo real (no conciliados por hora).

    Informes geográficos

    Dimensiones de la analítica geográfica

    • country- Como el código de país ISO-3611-1. p.ej: 'NOSOTROS'
    • region- Como el código de región ISO-3611-2. p.ej: 'US-WA'
    • city- Nombre de la ciudad. p.ej: Seattle

    Nota: Para países o regiones desconocidos, la API devuelve "ZZ" como código (según ISO-3611-alpha2).

    Campos y clasificación

    Utilizar el fields parámetro para especificar los campos que desea devolver. Por defecto, video_view se devuelve y el campo correspondiente a la dimensión sobre la que está informando (p. ej. destination_domain ) son devueltos. Ver dimensiones y campos para más detalles.

    Utilizar el sort parámetro para especificar qué campo de métrica se utiliza para ordenar los elementos devueltos; por ejemplo: sort=video_view. Puede invertir el orden de clasificación negando el campo de clasificación: sort= -video_view.

    Campos calculados

    Puede agregar campos calculados a sus solicitudes de API usando la sintaxis:

    fields=calulated_field_name:expression
    HTTP

    Puede utilizar campos calculados para crear sus propios campos personalizados a partir de métricas existentes o para cambiar el nombre de un campo existente.

    El nombre del campo calculado puede ser cualquier cadena compatible con URI. La expresión puede incluir nombres de campo regulares y los siguientes operadores aritméticos:

    • + (suma)
    • - (sustracción)
    • * (multiplicación)
    • / (división)
    • ^ (exponente)
    • () (paréntesis)

    Ejemplos

    fields=avg_seconds_viewed:video_seconds_viewed/video_view,video.name
    HTTP
    fields=avg_incomplete_ads:(ad_mode_begin-ad_mode_complete)/video_view,video.name
    HTTP
    fields=Video%20Views:video_view,video.name
    HTTP

    Solicitud de muestra

    Ejemplo de respuesta (a la solicitud anterior)

    {
      "item_count": 110,
      "items": [
        {
          "avg_seconds_viewed": 2152.2519913106444,
          "video.name": "Flamingos",
          "video_seconds_viewed": 2972260,
          "video": "4825279519001",
          "video_view": 1381
        },
        {
          "avg_seconds_viewed": 14.016225448334756,
          "video.name": "Tiger",
          "video_seconds_viewed": 16413,
          "video": "4093643993001",
          "video_view": 1171
        },
        {
          "avg_seconds_viewed": 12.06,
          "video.name": "Zebra",
          "video_seconds_viewed": 9045,
          "video": "3851389913001",
          "video_view": 750
        },
        {
          "avg_seconds_viewed": 23.343065693430656,
          "video.name": "Sea-SeaTurtle",
          "video_seconds_viewed": 15990,
          "video": "1754276205001",
          "video_view": 685
        }
      ],
      "summary": {
        "avg_seconds_viewed": 274.27374399301004,
        "video_seconds_viewed": 3139063,
        "video_view": 11445
      }
    }
    JSON