Ce guide présente le point de terminaison Chrome UX Report (CrUX) History API, qui fournit une série temporelle de données sur les performances Web. Ces données sont mises à jour chaque semaine et vous permettent de consulter environ six mois d'historique, avec 25 points de données espacés d'une semaine.
Avec les mises à jour quotidiennes du point de terminaison initial de l'API CrUX, vous pouvez désormais consulter rapidement les données les plus récentes et ce qui s'est passé auparavant. C'est donc un outil puissant pour voir les modifications d'une page Web au fil du temps.
Interroger l'API CrUX quotidienne
Pour récapituler un article précédent sur l'API CrUX, vous pouvez obtenir un instantané des données de champ pour une origine particulière de la manière suivante:
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 }
}
}
}
Cet instantané inclut les valeurs de densité de l'histogramme et les valeurs de centiles pour une période de collecte spécifique de 28 jours (du 27 décembre 2022 au 23 janvier 2023).
Interroger l'API CrUX History
Pour appeler le point de terminaison de l'historique, remplacez queryRecord dans l'URL par queryHistoryRecord dans la commande curl. Vous pouvez utiliser la même clé API CrUX que pour l'appel précédent.
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 forme générale d'une réponse est similaire, mais il y a beaucoup plus de données ! Au lieu d'un seul point de données, il existe désormais des séries temporelles pour les champs contenant les valeurs du 75e centile (p75) et de la densité de l'histogramme.
{
"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 }
}
]
}
}
Dans cet exemple, la série temporelle densities pour le bucket de 0 à 2 500 ms de la métrique Largest Contentful Paint (LCP) est [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Chacune de ces densités a été observée lors de l'entrée collectionPeriods correspondante. Par exemple, la cinquième densité, 0,9183, était la densité de la cinquième période de collecte, se terminant le 3 septembre 2022, et 0,9187 correspond à la densité pour la période se terminant la semaine suivante.
En d'autres termes, en interprétant les dernières entrées de séries temporelles dans l'exemple https://web.dev, il a été constaté que du 14 août 2022 au 10 septembre 2022, 91, 87% des chargements de page avaient des valeurs LCP inférieures à 2 500 ms, 5, 27% avaient des valeurs comprises entre 2 500 ms et 2, 0% supérieures à 4 000 ms.
De même, il existe une série temporelle pour les valeurs p75: le LCP p75 du 14 août 2022 au 10 septembre 2022 était de 1377. Cela signifie que, pour cette période de collecte, 75% des expériences utilisateur avaient un LCP inférieur à 1 377 ms, et 25% des expériences utilisateur avaient un LCP supérieur à 1 377 ms.
Alors que cet exemple ne répertorie que six entrées de séries temporelles et des périodes de collecte, les réponses de l'API fournissent 25 entrées de série temporelle. étant donné que chacune de ces périodes de collecte se termine le samedi à sept jours d'intervalle, cela couvre six mois.
Dans toute réponse donnée, la longueur de la série temporelle pour les densités de bins d'histogramme et pour les valeurs p75 sera exactement la même que la longueur du tableau dans le champ collectionPeriods: il existe une correspondance un à un basée sur l'index dans ces tableaux.
Interroger les données au niveau de la page
En plus des données au niveau de l'origine, l'API CrUX History permet d'accéder aux données historiques au niveau de la page. Alors que les données au niveau de l'origine étaient auparavant disponibles dans l'ensemble de données CrUX sur BigQuery (ou à l'aide du tableau de bord CrUX), les données historiques au niveau de la page n'étaient disponibles que si les sites collectaient et stockaient eux-mêmes les données. La nouvelle API libère désormais ces données historiques au niveau de la page.
Les données au niveau de la page peuvent être interrogées de la même manière, mais en utilisant url au lieu de origin dans la charge utile:
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/"}'
Les données historiques au niveau de la page (et de l'origine) sont soumises aux mêmes critères d'éligibilité que le reste de l'expérience utilisateur Chrome (CrUX). Il est donc possible que les pages en particulier ne disposent pas d'un historique complet. Dans ces cas, les éléments "manquants" les données seront représentées par "NaN" pour les densités histogramTimeseries et null pour percentilesTimeseries. La différence s'explique par le fait que les densités de l'histogramme sont toujours des nombres, tandis que les centiles peuvent être des nombres ou des chaînes (CLS utilise des chaînes, même si elles ressemblent à des nombres).
Visualiser les données
Alors, vous vous demandez peut-être pourquoi les données sont formées de cette manière ? Il s'avère que cela facilite la création de graphiques. Par exemple, voici un graphique des valeurs p75 pour Interaction To Next Paint (INP) pour https://web.dev:
Dans ce graphique en courbes, chaque valeur sur l'axe des y est une valeur p75 de la série temporelle p75s, et l'axe des x correspond au temps, qui est configuré en tant que lastDate pour chaque période de collecte.
Voici un graphique représentant la série temporelle d'un bin de l'histogramme, appelé graphique à trois bins, car ces histogrammes en comportent trois.
L'axe des x est configuré en tant que lastDate pour chaque période de collecte. Cette fois, l'axe des ordonnées correspond au pourcentage de chargements de page correspondant à une plage spécifique pour la métrique INP, représenté par un graphique à barres empilées. Le graphique p75 offre un aperçu rapide. Dans un seul graphique, il est relativement facile d'ajouter plusieurs métriques, ou d'afficher des lignes pour PHONE et DESKTOP. Le graphique à trois bins donne une idée de la distribution des valeurs des métriques mesurées au cours de chaque période de collecte.
Par exemple, même si le graphique p75 suggère que https://web.dev avait des valeurs INP presque acceptables pendant la période d'observation, le graphique des trois bins montre que l'INP était en fait faible pour une petite partie des chargements de page. Dans les deux graphiques, il est relativement facile de déduire qu'une régression des performances a débuté vers la fin du mois d'octobre et a été corrigée à la mi-novembre.
Pour générer ce type de graphiques vous-même, nous avons créé un exemple dans Colab. Colab, ou "Colaboratory", vous permet d'écrire et d'exécuter du code Python depuis votre navigateur. L'API CrUX History Colab (source) utilise Python pour appeler l'API et représenter les données dans un graphique.
Ce Colab vous permet de créer des graphiques au format p75 ou à trois bins, d'obtenir des données sous forme de tableau, et de voir la paire requête/réponse pour l'API CrUX en remplissant un court formulaire. Vous n'avez pas besoin d'être un programmeur pour utiliser cette fonctionnalité, mais vous pouvez examiner le code Python et le modifier pour obtenir un résultat étonnant. N'hésitez pas à nous faire part de vos commentaires.
Bien entendu, vous n'êtes pas limité à Colab ni à Python. Ce n'est qu'un exemple d'utilisation de cette nouvelle API. En tant que point de terminaison HTTP basé sur JSON, l'API peut être interrogée à partir de n'importe quelle technologie.
Conclusion
Avant le lancement du point de terminaison de l'API CrUX History, les propriétaires de sites ne disposaient que d'informations historiques limitées. Les données mensuelles au niveau de l'origine étaient disponibles dans BigQuery et le tableau de bord CrUX, mais pas les données hebdomadaires ni les données historiques au niveau de la page. Les propriétaires de sites pouvaient enregistrer ces données eux-mêmes à l'aide de l'API quotidienne, mais la nécessité de réaliser cette opération n'était souvent nécessaire qu'après une régression des métriques.
Avec le lancement de cette API CrUX History, l'objectif est d'aider les propriétaires de sites à mieux comprendre l'évolution des métriques de leur site et de l'utiliser comme outil de diagnostic en cas de problème. Si vous utilisez la nouvelle API, n'hésitez pas à nous faire part de vos commentaires dans le groupe Google "Discussions" sur l'expérience utilisateur Chrome.
Remerciements
Image principale de Dave Herring sur Unsplash