La API de CrUX brinda acceso de baja latencia a datos agregados de experiencia del usuario real en el nivel de detalle de la página y el origen.
Caso de uso común
La API de CrUX permite consultar métricas de experiencia del usuario para un URI específico, como "Obtén métricas para el origen de https://example.com
".
Clave de API de CrUX
Para usar la API de CrUX, se requiere una clave de API de Google Cloud. Puedes crear una en la página Credenciales y aprovisionarla para el uso de Chrome UX Report API
.
Una vez que tengas una clave de API, tu aplicación podrá agregar el parámetro de consulta key=[YOUR_API_KEY]
a todas las URLs de solicitud. Consulta Consultas de ejemplo.
La clave de API en las URL se incorpora de manera segura, por lo que no necesita codificación.
Modelo de datos
En esta sección, se detalla la estructura de los datos en las solicitudes y respuestas.
Registro
Es información discreta sobre una página o un sitio. Un registro puede tener datos específicos para un identificador y una combinación específica de dimensiones. Un registro puede contener datos de una o más métricas.
Identificadores
Los identificadores especifican qué registros se deben buscar. En CrUX, estos identificadores son páginas web y sitios web.
Origen
Si el identificador es un origen, se agregan juntos todos los datos presentes para todas las páginas de ese origen. Por ejemplo, supongamos que el origen http://www.example.com
tenía páginas según este mapa del sitio:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Esto significa que, cuando se consulta el Informe de UX de Chrome con el origen establecido en http://www.example.com
, se muestran los datos de http://www.example.com/
, http://www.example.com/foo.html
y http://www.example.com/bar.html
, en conjunto, porque todas esas páginas pertenecen a ese origen.
URLs
Si el identificador es una URL, solo se mostrarán los datos para esa URL específica. Volvamos al mapa del sitio de origen http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Si el identificador se establece en URL con el valor http://www.example.com/foo.html
, solo se mostrarán los datos de esa página.
Dimensiones
Las dimensiones identifican un grupo específico de datos con el que se agrega un registro. Por ejemplo, un factor de forma de PHONE
indica que el registro contiene información sobre las cargas que se produjeron en un dispositivo móvil. Cada dimensión tendrá una cierta cantidad de valores, y, implícitamente, la falta de especificarla significará que la dimensión se agregará a todos los valores. Por ejemplo, si no se especifica ningún factor de forma, significa que el registro contiene información sobre las cargas que se realizaron en cualquier factor de forma.
Factor de forma
Es la clase de dispositivo que el usuario final usó para navegar a la página. Esta es una clase general de dispositivo dividida en PHONE
, TABLET
y DESKTOP
.
Tipo de conexión real
El Tipo de conexión real es la calidad estimada de la conexión del dispositivo cuando navega a la página. Esta es una clase general dividida en offline
, slow-2G
, 2G
, 3G
y 4G
.
Métrica
Las métricas se informan como agregaciones estadísticas, en histogramas, percentiles y fracciones.
Los valores de punto flotante se redondean a 4 decimales (ten en cuenta que las métricas cumulative_layout_shift
están codificadas en formato doble como una cadena, por lo que no se consideran números de punto flotante y se informan con 2 decimales dentro de la cadena).
Histograma
Cuando las métricas se expresan en un histograma, se muestran los porcentajes de las cargas de página que corresponden a rangos particulares para esa métrica.
Un histograma simple de tres contenedores para una métrica de ejemplo se ve de la siguiente manera:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Estos datos indican que, para el 38.18% de las cargas de páginas, la métrica de ejemplo se midió entre 0 ms y 1,000 ms. Las unidades de la métrica no se encuentran en este histograma. En este caso, supondremos que son milisegundos.
Además, el 49.91% de las cargas de páginas tuvo un valor de métrica entre 1,000 ms y 3,000 ms, y el 11.92% observó un valor superior a 3,000 ms.
Percentiles
Las métricas también pueden contener percentiles que pueden ser útiles para realizar análisis adicionales. Informaremos valores de métricas específicos en el percentil determinado para esa métrica. Se basan en el conjunto completo de datos disponibles y no en los datos discretos finales, por lo que no necesariamente coinciden con un percentil interpolado que se basa en el histograma final discretizado.
{
"percentiles": {
"p75": 2063
}
}
En este ejemplo, al menos el 75% de las cargas de páginas se midieron con el valor de la métrica <= 2063
.
Fracciones
Las fracciones indican los porcentajes de cargas de página que se pueden etiquetar de una manera determinada. En este caso, los valores de la métrica son estas etiquetas.
Por ejemplo, la métrica form_factors
consta de un objeto fractions
que enumera el desglose de los factores de forma (o dispositivos) que abarca la consulta determinada:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
En este caso, el 3.77% de las cargas de páginas se midieron en una computadora de escritorio, el 2.88% en una tablet y el 93.35% en un teléfono, lo que da un total del 100%.
Tipos de valores de las métricas
Nombre de la métrica de la API de CrUX | Tipo de datos | Unidades métricas | Datos estadísticos | Documentación |
---|---|---|---|---|
cumulative_layout_shift |
Dos decimales con codificación doble como cadena | sin unidades | histograma con tres discretizaciones, percentiles con p75 | cls |
first_contentful_paint |
int | milésimas de segundo | histograma con tres discretizaciones, percentiles con p75 | FFC |
first_input_delay (obsoleto) |
int | milésimas de segundo | histograma con tres discretizaciones, percentiles con p75 | fideo |
interaction_to_next_paint |
int | milésimas de segundo | histograma con tres discretizaciones, percentiles con p75 | INP |
largest_contentful_paint |
int | milésimas de segundo | histograma con tres discretizaciones, percentiles con p75 | lcp |
experimental_time_to_first_byte |
int | milésimas de segundo | histograma con tres discretizaciones, percentiles con p75 | ttfb |
form_factors |
Doble decimal de 4 decimales | porcentaje | asignación del factor de forma a la fracción | factores de forma |
navigation_types |
Doble decimal de 4 decimales | porcentaje | asignación del tipo de navegación a la fracción | tipos de navegación |
Asignación de nombres de métricas de BigQuery
Nombre de la métrica de la API de CrUX | Nombre de la métrica de BigQuery |
---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
first_input_delay |
first_input.delay |
interaction_to_next_paint |
interaction_to_next_paint |
largest_contentful_paint |
largest_contentful_paint |
experimental_time_to_first_byte |
experimental.time_to_first_byte |
navigation_types |
navigation_types |
form_factors |
N/A |
Período de recopilación
A partir de octubre de 2022, la API de CrUX contiene un objeto collectionPeriod
con campos firstDate
y endDate
que representan las fechas de inicio y finalización de la ventana de agregación. Por ejemplo:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Esto permite una mejor comprensión de los datos y si ya se actualizaron para ese día o si muestran los mismos datos que ayer.
Ten en cuenta que la API de CrUX tiene un retraso de aproximadamente dos días con respecto a la fecha de hoy, ya que espera los datos completados del día, y requiere cierto tiempo de procesamiento para poder estar disponible en la API. Se utiliza la hora estándar del Pacífico (PST), sin cambios en el horario de verano.
Consultas de ejemplo
Las consultas se envían como objetos JSON mediante una solicitud POST a https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
con datos de consulta como un objeto JSON en el cuerpo de POST:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Por ejemplo, se puede llamar a esto desde curl
con la siguiente línea de comandos (reemplaza API_KEY
por tu clave):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
Los datos a nivel de página están disponibles a través de la API pasando una propiedad url
en la consulta, en lugar de origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Si no se configura la propiedad metrics
, se mostrarán todas las métricas disponibles:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(obsoleto)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(solo se informa si no se especifica ningúnformFactor
en la solicitud)
Si no se proporciona un valor de formFactor
, los valores se agregarán en todos los factores de forma.
Consulta Cómo usar la API de informe de UX de Chrome para ver más ejemplos de consultas.
Canalización de datos
El conjunto de datos de CrUX se procesa a través de una canalización para consolidar, agregar y filtrar los datos antes de que estén disponibles mediante la API.
El promedio móvil
Los datos del informe de UX de Chrome son un promedio móvil de 28 días de métricas agregadas. Esto significa que los datos que se presentan en el Informe de UX de Chrome en un momento dado son, en realidad, los datos de los últimos 28 días combinados.
Esto es similar a la forma en que el conjunto de datos de CrUX en BigQuery agrega informes mensuales.
Novedades diarias
Los datos se actualizan diariamente alrededor de las 04:00 UTC. No existe un acuerdo de nivel de servicio para los horarios de actualización, sino que se ejecuta según el criterio del mejor esfuerzo todos los días.
Esquema
Hay un solo extremo para la API de CrUX que acepta solicitudes HTTP POST
. La API muestra un objeto record
que contiene uno o más metrics
que corresponden a los datos de rendimiento sobre el origen o la página solicitados.
Solicitud HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
La URL usa la sintaxis de la transcodificación gRPC.
Cuerpo de la solicitud
El cuerpo de la solicitud debe contener datos con la siguiente estructura:
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
"metrics": [
string
],
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Campos | |
---|---|
effectiveConnectionType |
El tipo de conexión efectiva es una dimensión de consulta que especifica la clase de red efectiva a la que deben pertenecer los datos del registro. Este campo usa los valores Nota: Si no se especifica un tipo de conexión real, se mostrará un registro especial con datos agregados de todos los tipos de conexión vigentes. |
formFactor |
El factor de forma es una dimensión de consulta que especifica la clase de dispositivo a la que deben pertenecer los datos del registro. Este campo usa los valores Nota: Si no se especifica un factor de forma, se mostrará un registro especial con datos agregados de todos los factores de forma. |
metrics[] |
Las métricas que se deben incluir en la respuesta. Si no se especifica ninguna, se mostrarán las métricas encontradas. Valores permitidos: |
Campo de unión url_ . El url_pattern es el identificador principal para una búsqueda de registros. Puede ser solo una de las siguientes opciones: |
|
origin |
El "origen" de Ejemplos: |
url |
El Ejemplos: |
Por ejemplo, para solicitar los valores de procesamiento de imagen con contenido más altos para computadoras de escritorio para la página principal de la documentación para desarrolladores de Chrome:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Cuerpo de la respuesta
Las solicitudes exitosas muestran respuestas con un objeto record
y urlNormalizationDetails
en la siguiente estructura:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Por ejemplo, la respuesta al cuerpo de la solicitud en la solicitud anterior podría ser la siguiente:
{
"record": {
"key": {
"formFactor": "DESKTOP",
"url": "https://developer.chrome.com/docs/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.9815
},
{
"start": 2500,
"end": 4000,
"density": 0.0108
},
{
"start": 4000,
"density": 0.0077
}
],
"percentiles": {
"p75": 651
}
}
},
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
}
}
Clave
Key
define todas las dimensiones que identifican este registro como únicas.
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Campos | |
---|---|
formFactor |
El factor de forma es la clase de dispositivo que utilizaron todos los usuarios para acceder al sitio para este registro. Si no se especifica el factor de forma, se mostrarán los datos agregados de todos los factores de forma. |
effectiveConnectionType |
El tipo de conexión efectiva es la clase de conexión general que experimentaron todos los usuarios para este registro. Este campo usa los valores ["offline", "slow-2G", "2G", "3G", "4G"] como se especifica en: https://wicg.github.io/netinfo/#effective-connection-types Si no se especifica el tipo de conexión real, se mostrarán los datos agregados de todos los tipos de conexión efectivos. |
Campo de unión url_ . El patrón de URL es la URL a la que se aplica el registro. Las direcciones (url_ ) solo pueden ser una de las siguientes opciones: |
|
origin |
Nota: Cuando se especifica un valor |
url |
Nota: Cuando se especifica una |
Métricas
Un metric
es un conjunto de datos agregados sobre la experiencia del usuario para una sola métrica de rendimiento web, como el primer procesamiento de imagen con contenido.
Puede contener un histograma de resumen del uso real de Chrome como una serie de bins
, datos de percentiles específicos
(como p75) o fracciones etiquetadas.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
o
{
"fractions": {
object (Fractions)
}
}
Campos | |
---|---|
histogram[] |
Es el histograma de experiencias del usuario para una métrica. El histograma tendrá al menos un intervalo y las densidades de todos los discretizaciones sumarán alrededor de 1. |
percentiles |
Percentiles útiles comunes de la métrica. El tipo de valor para los percentiles será el mismo que los tipos de valor especificados para las discretizaciones de histograma. |
fractions |
Este objeto contiene fracciones etiquetadas que suman ~1. Las fracciones se redondean con 4 decimales. |
Depósito
Un bin
es una porción discreta de datos que abarca de principio a fin o si no se da ningún final desde el inicio hasta el infinito positivo.
Los valores de inicio y finalización de una discretización se proporcionan en el tipo de valor de la métrica que representa. Por ejemplo, el primer procesamiento de imagen con contenido se mide en milisegundos y se expone como ints, por lo que sus contenedores de métricas usarán int32s para sus tipos de inicio y finalización. Sin embargo, el cambio de diseño acumulado se mide en decimales sin unidades y se expone como un decimal codificado como una cadena, por lo que sus discretizaciones de métricas usarán cadenas para su tipo de valor.
{
"start": value,
"end": value,
"density": number
}
Campos | |
---|---|
start |
El inicio es el principio del depósito de datos. |
end |
El final es el final de los contenedores de datos. Si no se propaga el valor, entonces el intervalo no tiene ningún final y es válido desde el inicio hasta el +inf. |
density |
Es la proporción de usuarios que experimentaron el valor de esta discretización para la métrica determinada. Las densidades se redondean con 4 decimales. |
Percentiles
Percentiles
contiene valores sintéticos de una métrica en un percentil estadístico determinado. Se usan para calcular el valor de una métrica según la experiencia de un porcentaje de usuarios del total de usuarios.
{
"P75": value
}
Campos | |
---|---|
p75 |
El 75% de las cargas de páginas experimentaron la métrica determinada a este valor o menos. |
Fracciones
Fractions
contiene fracciones etiquetadas cuya suma es igual a 1. Cada etiqueta describe una carga de página de alguna manera, por lo que se puede considerar que las métricas representadas de esta manera producen valores distintos en lugar de valores numéricos, y las fracciones expresan la frecuencia con la que se midió un valor distinto en particular.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Al igual que los valores de densidad en las discretizaciones de histograma, cada fraction
es un número 0.0 <= value <= 1.0
, y suman alrededor de 1.0.
UrlNormalization
Objeto que representa las acciones de normalización tomadas para normalizar una URL con el objetivo de lograr una mayor probabilidad de que la búsqueda sea exitosa Estos son cambios automáticos simples que se realizan cuando se busca el url_pattern
proporcionado y se produce un error. No se administran las acciones complejas, como los siguientes redireccionamientos.
{
"originalUrl": string,
"normalizedUrl": string
}
Campos | |
---|---|
originalUrl |
Es la URL original solicitada antes de cualquier acción de normalización. |
normalizedUrl |
La URL después de cualquier acción de normalización. Esta es una URL de experiencia del usuario válida que podría buscarse razonablemente. |
Límites de frecuencia
La API de CrUX tiene un límite de 150 consultas por minuto por proyecto de Google Cloud, que se ofrecen sin cargo. Puedes consultar este límite y tu uso actual en la consola de Google Cloud. Esta amplia cuota debería ser suficiente para la gran mayoría de los casos de uso, y no es posible pagar una cuota mayor.