En esta guía, se presenta el extremo de la API de History del Informe de UX de Chrome (CrUX), que proporciona series temporales de datos de rendimiento web. Estos datos se actualizan semanalmente y te permiten ver un historial de aproximadamente 6 meses, con 25 datos espaciados por una semana.
Cuando se usa con las actualizaciones diarias del extremo de la API de CrUX original, ahora puedes ver rápidamente los datos más recientes y lo que sucedió anteriormente, lo que la convierte en una herramienta potente para ver los cambios en las páginas web a lo largo del tiempo.
Prueba la API en esta página
Cómo consultar la API de CrUX diaria
Para recapitular un artículo anterior sobre la API de CrUX, puedes obtener un resumen de los datos de campo de 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 }
}
}
}
Esta instantánea incluye valores de densidad de histograma y valores de percentiles para un período de recopilación específico de 28 días, en este caso, del 27 de diciembre de 2022 al 23 de enero de 2023.
Consulta la API de History de CrUX
Para llamar al extremo de historial, cambia queryRecord en la URL a queryHistoryRecord en el comando curl. Funcionará usar la misma clave de API de CrUX que se usó en la llamada anterior.
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 del 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 intervalo de 0 a 2,500 ms de la métrica Largest Contentful Paint (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 densidad del quinto período de recopilación, que finalizó el 3 de septiembre de 2022, y 0.9187 fue la densidad del período que finalizó la semana posterior.
En otras palabras, interpretando las últimas entradas de las 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 que 2,500 ms, el 5.27% tenía valores entre 2,500 ms y 4,000 ms, y el 2.85% tenía valores superiores a 4,000 ms.
Del mismo modo, hay una serie temporal para los valores del P75: el P75 de la LCP del 14 de agosto de 2022 al 10 de septiembre de 2022 fue 1377. Esto significa que, durante este período de recopilación, el 75% de las experiencias del usuario tuvo un LCP inferior a 1,377 ms y el 25% tuvo un LCP superior a 1,377 ms.
Si bien el ejemplo solo enumera 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 abarca 6 meses.
En cualquier respuesta, la longitud de las series temporales para las densidades de intervalos del histograma y para los valores de p75 será exactamente la misma que la longitud del array en el campo collectionPeriods: Hay una correspondencia uno a uno según el índice en estos arrays.
Cómo 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 los 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 por sí mismos. La nueva API ahora desbloquea esos 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 con 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 histogramTimeseries y null para percentilesTimeseries. El motivo de la diferencia es que las densidades del histograma siempre son 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 la creación de gráficos. Por ejemplo, este es un gráfico de los valores del 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 de p75 de la serie temporal p75s, y el eje X es la hora, que se configura como lastDate para cada período de recopilación.
Este es un gráfico de las series temporales de los intervalos del histograma, conocido como gráfico de tres intervalos, porque estos histogramas tienen tres intervalos.
El eje X se configura como el lastDate para cada período de recopilación. Sin embargo, esta vez, el eje Y es el porcentaje de cargas de página que se encuentran en un rango específico para la métrica INP, que se muestra a través de un gráfico de barras apiladas. El gráfico del 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 intervalos proporciona una idea de la distribución de los valores de las métricas medidos durante cada período de recopilación.
Por ejemplo, aunque el gráfico del p75 sugiere que https://web.dev tuvo valores de INP casi aceptables durante el período de observación, el gráfico de tres intervalos muestra que, para una pequeña fracción de cargas de página, el INP fue realmente bajo. 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 ejemplo de Colab. Colab, o "Colaboratory", te permite escribir y ejecutar código de Python desde tu navegador. El Colab de la API de CrUX History (fuente) usa Python para realizar llamadas a la API y graficar los datos.
Este Colab te permite completar un breve formulario para crear gráficos de p75, gráficos de tres intervalos, obtener datos en formato tabular y ver el par de solicitud y respuesta de la API de CrUX. No es necesario que seas programador para usar esto, pero puedes mirar el código de Python y modificarlo para crear algo asombroso. Disfrútala y no dudes en enviarnos tus comentarios sobre lo que encuentres.
Por supuesto, no te limitas 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 sitios tenían limitaciones en la información histórica que podían obtener de CrUX. Los datos mensuales a nivel del origen estaban disponibles en BigQuery y en el panel de CrUX, pero no los datos semanales ni los históricos a nivel de la página. Los propietarios del sitio podían registrar estos datos por su cuenta con la API diaria, pero a menudo la necesidad de hacerlo solo se descubría después de una regresión en las métricas.
La esperanza con la introducción de esta API de CrUX History es que permitirá a los propietarios de sitios comprender mejor las métricas cambiantes de sus sitios y usarla como herramienta de diagnóstico cuando surjan problemas. Si usas la nueva API, puedes enviar comentarios en el grupo de Google de Chrome UX Report (Discussions).
Agradecimientos
Imagen hero de Dave Herring en Unsplash