En esta guía, se presenta el extremo de la API de historial de informes de UX de Chrome (CrUX), que proporciona series temporales de datos de rendimiento web. Estos datos se actualizan semanalmente y te permiten ver alrededor de 6 meses de historial, con 25 datos espaciados por una semana.
Cuando se usa con las actualizaciones diarias del extremo original de la API de CrUX, ahora puedes ver con rapidez los datos más recientes y lo que sucedió antes, lo que lo convierte en una herramienta potente para ver los cambios de páginas web a lo largo del tiempo.
Cómo consultar la API de CrUX diaria
En resumen de un artículo anterior sobre la API de CrUX, puedes obtener una instantánea de los datos de campo para un origen en particular de la siguiente manera:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
En este resumen, se incluyen los valores de densidad de histogramas y los valores de percentiles para un período particular de recopilación de 28 días, del 27 de diciembre de 2022 al 23 de enero de 2023.
Consulta la API de CrUX History
Para llamar al extremo del historial, cambia queryRecord en la URL a queryHistoryRecord en el comando curl. El uso de la misma clave de API de CrUX que usaste para la llamada anterior funcionará.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
La forma general de una respuesta es similar, ¡pero hay muchos más datos! En lugar de un solo dato, ahora hay series temporales para los campos que contienen el percentil 75 (p75) y los valores de densidad de histograma.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
En este ejemplo, la serie temporal densities para el bucket de 0 a 2,500 ms de la métrica Procesamiento de imagen con contenido más grande (LCP) es [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Cada una de estas densidades se observó durante la entrada collectionPeriods correspondiente. Por ejemplo, la quinta densidad, 0.9183, fue la del quinto período de recolección, que finalizó el 3 de septiembre de 2022, y 0.9187 fue la del período que terminó la semana siguiente.
En otras palabras, cuando se interpretaban las últimas entradas de series temporales en el ejemplo de https://web.dev, se descubrió que, desde el 14 de agosto de 2022 hasta el 10 de septiembre de 2022, el 91.87% de las cargas de página tenían valores de LCP menores a 2,500 ms, el 5.27% tenía valores entre 2,500 ms y 4,000 ms.
Del mismo modo, hay una serie temporal para los valores p75: el LCP p75 del 14 de agosto de 2022 al 10 de septiembre de 2022 fue 1377. Esto significa que, para este período de recopilación, el 75% de las experiencias del usuario tuvo un LCP inferior a 1,377 ms y el 25% de las experiencias del usuario tuvo un LCP superior a 1,377 ms.
Si bien en el ejemplo solo se enumeran 6 entradas de series temporales y períodos de recopilación, las respuestas de la API proporcionan 25 entradas de series temporales. Dado que las fechas de finalización de cada uno de estos períodos de recopilación son sábados con 7 días de diferencia, esto cubre 6 meses.
En cualquier respuesta determinada, la longitud de las series temporales para las densidades de discretización de histogramas y los valores p75 será exactamente la misma que la longitud del array en el campo collectionPeriods. Existe una correspondencia uno a uno basada en el índice en estos arrays.
Consultar datos a nivel de la página
Además de los datos a nivel del origen, la API de CrUX History permite acceder a datos históricos a nivel de la página. Si bien los datos a nivel del origen estaban disponibles anteriormente con el conjunto de datos de CrUX en BigQuery (o con el panel de CrUX), los datos históricos a nivel de la página solo estaban disponibles si los sitios recopilaban y almacenaban los datos ellos mismos. La nueva API ahora desbloquea los datos históricos a nivel de la página.
Los datos a nivel de la página se pueden consultar de la misma manera, pero mediante url en lugar de origin en la carga útil:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Los datos históricos a nivel de la página (y del origen) están sujetos a los mismos requisitos de elegibilidad que el resto de CrUX, por lo que es posible que las páginas, en particular, no tengan un registro histórico completo. En estos casos, los datos "faltantes" se representarán con "NaN" para las densidades de histogramTimeseries y null para las percentilesTimeseries. La razón de la diferencia es que las densidades de los histogramas son siempre números, mientras que los percentiles pueden ser números o cadenas (CLS usa cadenas, incluso si parecen números).
Visualiza los datos
Entonces, te preguntarás, ¿por qué los datos tienen esta forma? Se descubrió que esto facilita el trazado de gráficos. Por ejemplo, a continuación, se muestra un gráfico de los valores p75 de Interaction To Next Paint (INP) para https://web.dev:
En este gráfico de líneas, cada valor del eje y es un valor p75 de la serie temporal p75s, y el eje X es el tiempo, que se configura como lastDate para cada período de recopilación.
A continuación, se muestra un gráfico de la serie temporal de discretización de histogramas, conocida como gráfico de tres intervalos, porque estos histogramas tienen tres discretizaciones.
El eje X se configura como lastDate para cada período de recopilación. Sin embargo, esta vez, el eje Y es el porcentaje de cargas de página que corresponden a un intervalo específico para la métrica INP, que se muestra mediante un gráfico de barras apiladas. El gráfico p75 proporciona una descripción general rápida y, dentro de un solo gráfico, es relativamente fácil agregar varias métricas o mostrar líneas para PHONE y DESKTOP. El gráfico de tres discretizaciones da una idea de la distribución de los valores de métricas medidos durante cada período de recopilación.
Por ejemplo, aunque el gráfico p75 sugiere que https://web.dev tenía valores de INP casi aceptables durante el período de observación, el gráfico de tres discretizaciones muestra que para una pequeña fracción de las cargas de página, el INP era realmente deficiente. En ambos gráficos, es relativamente fácil inferir que hubo una regresión de rendimiento que comenzó a fines de octubre y se corrigió a mediados de noviembre.
Para generar estos gráficos por tu cuenta, creamos un Colab de ejemplo. Colab, o Colaboratory, te permite escribir y ejecutar código de Python desde tu navegador. La API de Colab de CrUX History (fuente) usa Python para realizar llamadas a la API y graficar los datos.
Este Colab te permite crear gráficos p75 y gráficos de tres contenedores, obtener datos en formato tabular y ver el par de solicitud y respuesta de la API de CrUX completando un breve formulario. No necesitas ser programador para usar esto, pero, sin duda, puedes mirar el código de Python y modificarlo para lograr algo increíble. Disfrútalo y no dudes en enviarnos tus comentarios sobre lo que encuentres.
Por supuesto que no estás limitado a Colab o Python, y este es solo un ejemplo de cómo usar esta nueva API. Como extremo HTTP basado en JSON, la API se puede consultar desde cualquier tecnología.
Conclusión
Antes de la introducción del extremo de la API de CrUX History, los propietarios de los sitios tenían limitaciones en la información histórica que podían obtener de CrUX. Los datos mensuales a nivel de origen estaban disponibles con BigQuery y el panel de CrUX, pero los datos semanales no estaban disponibles ni los datos históricos a nivel de página. Los propietarios de los sitios podían registrar estos datos ellos mismos utilizando la API diaria, pero a menudo la necesidad de esto solo se descubrió después de una regresión en las métricas.
Con la introducción de esta API de CrUX History, esperamos que los propietarios de sitios puedan comprender mejor los cambios en las métricas de sus sitios y que sirvan como herramienta de diagnóstico para cuando surjan problemas. Si usas la nueva API, puedes enviar comentarios al Grupo de Google sobre los informes sobre la UX de Chrome (debates).
Agradecimientos
Hero image de Dave Herring en Unsplash