En esta guía, se presenta el extremo de la API de historial de Chrome UX Report (CrUX), que proporciona series temporales de datos de rendimiento web. Estos datos se actualizan semanalmente y te permiten ver un historial de unos 6 meses, con 25 datos separados por una semana.
Cuando se usa con las actualizaciones diarias del extremo original de la API de CrUX, puedes ver rápidamente los datos más recientes y lo que sucedió antes, lo que la convierte en una herramienta potente para ver los cambios en las páginas web a lo largo del tiempo.
Consulta 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 esta instantánea, se incluyen los valores de densidad de histogramas y valores de percentiles para un período de recopilación de 28 días en particular, en este caso, 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. Funcionará con la misma clave de API de CrUX que 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 de histogramas.
{
"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 correspondiente de collectionPeriods. Por ejemplo, la quinta densidad, 0.9183, fue la del quinto período de recopilación, que finalizó el 3 de septiembre de 2022, y 0.9187, la del período que terminó la semana posterior.
En otras palabras, después de interpretar las últimas entradas de series temporales del 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 inferiores a 2,500 ms, el 5.27% tenía valores entre 2500 ms y 4,200.5 ms, y 4,200.5%
De manera similar, hay una serie temporal para los valores de 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 de los usuarios tuvieron un LCP inferior a 1,377 ms y el 25% de las experiencias de los usuarios tuvieron 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; ya que las fechas de finalización de cada uno de estos períodos de recolección son los sábados con 7 días de diferencia: esto abarca 6 meses.
En cualquier respuesta dada, la longitud de las series temporales de las densidades de discretización de histogramas y de p75 será exactamente la misma que la longitud del array en el campo collectionPeriods: hay una correspondencia uno a uno basada en el índice en estos arrays.
Consulta datos a nivel de la página
Además de los datos a nivel del origen, la API de CrUX History permite el acceso a los datos históricos a nivel de la página. Si bien los datos a nivel de origen estaban disponibles anteriormente a través del conjunto de datos de CrUX en BigQuery (o mediante el panel de CrUX), los datos históricos a nivel de 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 a nivel del origen) están sujetos a los mismos requisitos de elegibilidad que el resto de la CrUX, por lo que es posible que las páginas no tengan un registro histórico completo. En estos casos, el error "faltante" Los datos se representarán mediante "NaN" para las densidades de histogramTimeseries y null para percentilesTimeseries. El motivo de la diferencia es que las densidades de 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 se moldean de esta manera? Se descubrió que esto facilita el trazado de los gráficos. Por ejemplo, este es un gráfico de los valores de p75 de Interaction To Next Paint (INP) de 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 el tiempo, que se configura como lastDate para cada período de recolección.
Aquí hay un grafo de la serie temporal de discretizaciones de histogramas, conocida como gráfico de tres discretizaciones, porque estos histogramas tienen tres discretizaciones.
El eje x se configura como lastDate para cada período de recolección. Sin embargo, esta vez, el eje Y es el porcentaje de cargas de página que entran 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 de 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 las métricas medidos durante cada período de recopilación.
Por ejemplo, aunque el gráfico p75 sugiere que https://web.dev tuvo valores de INP casi aceptables durante el período de observación, el gráfico tri-bin muestra que, para una pequeña fracción de las cargas de páginas, el INP fue en realidad malo. En ambos gráficos, es relativamente fácil inferir que hubo una regresión de rendimiento que comenzó a fines de octubre y que se corrigió a mediados de noviembre.
Para generar estos gráficos por tu cuenta, creamos un ejemplo de Colab. Un Colab, o Colaboratory, te permite escribir y ejecutar Python desde tu navegador. La API de Colab de la API de CrUX History (fuente) usa Python para realizar llamadas a la API y crear gráficos con los datos.
Esta Colab te permite crear gráficos p75 y tribin, obtener datos en formato tabular y ver el par de solicitudes y respuestas 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 hacer algo asombroso. Esperamos que disfrutes este video y no dudes en enviarnos 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 estaban limitados en la información histórica que podían obtener de CrUX. Los datos mensuales a nivel de origen estaban disponibles a través de BigQuery y el panel de CrUX, pero los datos semanales no estaban disponibles ni los datos históricos a nivel de la 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 les permita a los propietarios de los sitios comprender mejor las métricas cambiantes de su sitio y que funcione como una herramienta de diagnóstico para cuando surjan problemas. Si usas la nueva API, puedes enviar comentarios al Grupo de Google del Informe sobre la experiencia del usuario en Chrome (Debates).
Agradecimientos
Hero image de Dave Herring en Unsplash