La API de CrUX proporciona acceso de baja latencia a datos agregados de la 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 las métricas de la experiencia del usuario para un URI específico, como "Obtener métricas para el origen https://example.com".
Clave de API de CrUX
Para usar la API de CrUX, se requiere una clave de API de Google Cloud aprovisionada para el uso de Chrome UX Report API.
Adquiere y usa una clave de API
Obtén una claveO bien crea una en la página Credenciales.
Una vez que tienes una clave de API, puedes usar tu aplicación para adjuntar el parámetro de consulta key=yourAPIKey a todas las URL de solicitud.
La clave de API en las URL se incorpora de manera segura, por lo que no necesita codificación.
Consulta Ejemplos de consultas.
Modelo de datos
En esta sección, se detalla la estructura de los datos en las solicitudes y respuestas.
Grabar
Es un dato discreto sobre una página o un sitio. Un registro puede tener datos específicos para un identificador y para 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
Cuando el identificador es un origen, todos los datos presentes para todas las páginas de ese origen se agregan. Por ejemplo, supongamos que el origen http://www.example.com tenía páginas como las que se describen en 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 consulte el informe de UX de Chrome con el origen establecido en http://www.example.com, se mostrarán los datos de http://www.example.com/, http://www.example.com/foo.html y http://www.example.com/bar.html agregados, ya que todas son páginas de ese origen.
URL
Cuando el identificador sea una URL, solo se mostrarán los datos de esa URL específica. Volvamos a ver el mapa del sitio de origen de 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 de 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 cargas que se realizaron en un dispositivo móvil. Cada dimensión tendrá una cantidad determinada de valores, y la falta de especificación de esa dimensión implicará que se agregue a todos los valores de forma implícita. Por ejemplo, si no especificas ningún factor de forma, se indica 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 usó el usuario final para navegar a la página. Esta es una clase general de dispositivos dividida en PHONE, TABLET y DESKTOP.
Métrica
Registramos las métricas 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 son números dobles codificados como una cadena, por lo que no se consideran números de punto flotante y se informan a 2 decimales dentro de la cadena).
Histograma
Cuando las métricas se expresan en un histograma, mostramos los porcentajes de cargas de página que se encuentran en rangos particulares para esa métrica.
Un histograma de tres intervalos 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ágina, la métrica de ejemplo se midió entre 0 ms y 1,000 ms. Las unidades de la métrica no se incluyen en este histograma. En este caso, asumiremos milisegundos.
Además, el 49.91% de las cargas de página tuvo un valor de métrica entre 1,000 ms y 3,000 ms, y el 11.92% registró 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. Informamos 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 finales agrupados, por lo que no coinciden necesariamente con un percentil interpolado que se basa en el histograma agrupado final.
{
"percentiles": {
"p75": 2063
}
}
En este ejemplo, al menos el 75% de las cargas de página se midieron con un valor de métrica <= 2063.
Fracciones
Las fracciones indican los porcentajes de cargas de página que se pueden etiquetar de una manera particular. En este caso, los valores de las métricas 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ágina 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 métricas
| Nombre de la métrica de la API de CrUX | Tipo de datos | Unidades métricas | Agregaciones estadísticas | Documentación |
|---|---|---|---|---|
cumulative_layout_shift |
2 decimales con codificación doble como cadena | sin unidades | histograma con tres intervalos, percentiles con p75 | cls |
first_contentful_paint |
int | milisegundos | histograma con tres intervalos, percentiles con p75 | fcp |
interaction_to_next_paint |
int | milisegundos | histograma con tres intervalos, percentiles con p75 | inp |
largest_contentful_paint |
int | milisegundos | histograma con tres intervalos, percentiles con p75 | lcp |
experimental_time_to_first_byte |
int | milisegundos | histograma con tres intervalos, percentiles con p75 | ttfb |
form_factors |
Número doble de 4 decimales | porcentaje | asignación de factor de forma a fracción | factores de forma |
navigation_types |
Número doble de 4 decimales | porcentaje | asignación del tipo de navegación a una fracción | tipos de navegación |
round_trip_time |
int | milisegundos | percentiles con p75 | rtt |
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 |
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 |
round_trip_time |
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 del período de agregación. Por ejemplo:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Esto permite comprender mejor 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 aproximadamente dos días de retraso con respecto a la fecha actual, ya que espera los datos completos del día y hay un tiempo de procesamiento antes de que estén disponibles en la API. La zona horaria que se usa es la hora estándar del Pacífico (PST) sin cambios para el horario de verano.
Además, collectionPeriod siempre mostrará 28 días, incluso si los datos no corresponden a los 28 días completos (por ejemplo, si una página se lanzó hace menos de 28 días). collectionPeriod es el período durante el cual se agregaron los datos de CrUX, no necesariamente el período que representan los datos.
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 los 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 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 la página están disponibles a través de la API. Para ello, pasa 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_shiftfirst_contentful_paintinteraction_to_next_paintlargest_contentful_paintexperimental_time_to_first_bytenavigation_typesform_factors(solo se informa si no se especificaformFactoren 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 Chrome UX Report 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 a través de la API.
El promedio móvil
Los datos del informe de UX de Chrome son un promedio móvil de 28 días de las métricas agregadas. Esto significa que los datos que se presentan en el informe de UX de Chrome en un momento determinado son, en realidad, datos de los últimos 28 días agregados.
Esto es similar a la forma en que el conjunto de datos de CrUX en BigQuery agrega informes mensuales.
Actualizaciones diarias
Los datos se actualizan todos los días alrededor de las 04:00 UTC. No hay un acuerdo de nivel de servicio para los tiempos de actualización; se ejecuta todos los días según el criterio del mejor esfuerzo.
Esquema
Hay un solo extremo para la API de CrUX que acepta solicitudes HTTP POST. La API muestra un record que contiene uno o más metrics correspondientes 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:
{
"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 | |
|---|---|
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[] |
Son las métricas que se deben incluir en la respuesta. Si no se especifica ninguna, se mostrarán todas las métricas que se encuentren. Valores permitidos: |
Campo de unión url_. url_pattern es el identificador principal de una búsqueda de registro. Solo puede ser uno de los siguientes: |
|
origin |
El "origen" de Ejemplos: |
url |
El Ejemplos: |
Por ejemplo, para solicitar los valores de Largest Contentful Paint para computadoras de escritorio de la página principal de la documentación para desarrolladores de Chrome, haz lo siguiente:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Cuerpo de la respuesta
Las solicitudes correctas 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 único.
{
"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 todos los usuarios usaron para acceder al sitio de este registro. Si no se especifica el factor de forma, se mostrarán los datos agregados de todos los factores de forma. |
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 |
url |
Nota: Cuando especifiques un |
Métricas
Un metric es un conjunto de datos agregados de 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 el p75), o puede contener fracciones etiquetadas.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
o
{
"fractions": {
object (Fractions)
}
}
| Campos | |
|---|---|
histogram[] |
El histograma de las experiencias del usuario para una métrica. El histograma tendrá al menos un intervalo, y las densidades de todos los intervalos suman alrededor de 1. |
percentiles |
Percentiles útiles comunes de la métrica. El tipo de valor de los percentiles será el mismo que el de los intervalos del histograma. |
fractions |
Este objeto contiene fracciones etiquetadas, que suman alrededor de 1. Las fracciones se redondean a 4 decimales. |
Depósito
Un bin es una parte discreta de datos que abarca desde el principio hasta el final, o si no se proporciona un final, desde el principio hasta el infinito positivo.
Los valores de inicio y finalización de un intervalo 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 int, por lo que sus intervalos de métricas usarán int32 para sus tipos de inicio y finalización. Sin embargo, el cambio de diseño acumulativo se mide en decimales sin unidades y se expone como un decimal codificado como una cadena. Por lo tanto, sus intervalos de métricas usarán cadenas para su tipo de valor.
{
"start": value,
"end": value,
"density": number
}
| Campos | |
|---|---|
start |
Inicio es el comienzo del contenedor de datos. |
end |
End es el final del contenedor de datos. Si no se propaga el valor de fin, el intervalo no tiene un final y es válido desde el inicio hasta +inf. |
density |
Es la proporción de usuarios que experimentaron el valor de este intervalo para la métrica determinada. Las densidades se redondean a 4 decimales. |
Percentiles
Percentiles contiene valores sintéticos de una métrica en un percentil estadístico determinado. Se usan para estimar el valor de una métrica según lo experimentó un porcentaje de usuarios de la cantidad total de usuarios.
{
"P75": value
}
| Campos | |
|---|---|
p75 |
El 75% de las cargas de página experimentaron la métrica determinada en este valor o menos. |
Fracciones
Fractions contiene fracciones etiquetadas que suman alrededor de 1. Cada etiqueta describe una carga de página de alguna manera, por lo que las métricas representadas de esta manera se pueden considerar como productoras de valores distintos en lugar de valores numéricos, y las fracciones expresan con qué frecuencia se midió un valor distinto en particular.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Al igual que los valores de densidad en los intervalos de histograma, cada fraction es un número 0.0 <= value <= 1.0 y suman alrededor de 1.0.
UrlNormalization
Es un objeto que representa las acciones de normalización que se realizan para normalizar una URL y aumentar las probabilidades de que la búsqueda se realice correctamente. Estos son cambios automatizados simples que se realizan cuando se busca el url_pattern proporcionado que se sabe que fallará. No se controlan las acciones complejas, como seguir redireccionamientos.
{
"originalUrl": string,
"normalizedUrl": string
}
| Campos | |
|---|---|
originalUrl |
La URL solicitada original 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 se podría buscar de forma razonable. |
Límites de frecuencia
La API de CrUX se limita a 150 consultas por minuto por proyecto de Google Cloud, que se ofrece sin cargo. Puedes ver este límite y tu uso actual en la consola de Google Cloud. Esta cuota generosa debería ser suficiente para la gran mayoría de los casos de uso, y no es posible pagar por una cuota mayor.