Ce guide présente le point de terminaison de l'API Chrome UX Report (CrUX) History, qui fournit des séries temporelles de données de performances Web. Ces données sont mises à jour chaque semaine et vous permettent de consulter l'équivalent de 6 mois d'historique, avec 25 points de données espacés d'une semaine.
Combiné aux mises à jour quotidiennes du point de terminaison d'origine de l'API CrUX, vous pouvez désormais voir rapidement les données les plus récentes et ce qui s'est passé précédemment. Il s'agit donc d'un outil efficace pour visualiser les modifications apportées aux pages Web au fil du temps.
Interroger l'API CrUX quotidienne
Récapitulons un article précédent sur l'API CrUX. Vous pouvez obtenir un instantané des données réelles d'une origine comme suit:
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é comprend les valeurs de densité de l'histogramme et les valeurs de centile pour une période de collecte spécifique de 28 jours, dans ce cas, 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 globale 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 le 75e centile (p75) et les valeurs de 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, correspond à la densité pour la cinquième période de collecte, qui se termine le 3 septembre 2022, et 0,9187 à la densité de la période se terminant la semaine suivante.
En d'autres termes, en interprétant les dernières entrées de séries temporelles de l'exemple pour https://web.dev, nous avons constaté qu'entre le 14 août 2022 et le 10 septembre 2022, 91,87 % des chargements de page avaient des valeurs LCP inférieures à 2 500 ms, 5,27 % comportaient des valeurs comprises entre 2 500 ms et 4 000 ms, et 04 005 ms, et 0,04 ms, 0,04 ms,04 ms
De même, il existe une série temporelle pour les valeurs p75: la valeur p75 du LCP du 14 août 2022 au 10 septembre 2022 était 1377. Cela signifie que, pour cette période de collecte, 75% des expériences utilisateur ont eu un LCP inférieur à 1 377 ms et 25% des expériences utilisateur ont un LCP supérieur à 1 377 ms.
Alors que l'exemple ne répertorie que 6 entrées de séries temporelles et périodes de collecte, les réponses de l'API fournissent 25 entrées de séries temporelles. Puisque les dates de fin de chacune de ces périodes de collecte sont des samedis à sept jours d'intervalle, cela couvre six mois.
Dans une réponse donnée, la longueur de la série temporelle pour les densités de bins de l'histogramme et pour les valeurs p75 sera exactement identique à 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
Outre les données au niveau de l'origine, l'API CrUX History permet d'accéder aux données historiques au niveau de la page. Auparavant, les données au niveau de l'origine étaient disponibles à l'aide de l'ensemble de données CrUX sur BigQuery (ou du tableau de bord CrUX). Toutefois, les données historiques au niveau de la page n'étaient disponibles que si les sites collectaient et stockaient les données elles-mêmes. La nouvelle API débloque 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. Par conséquent, certaines pages peuvent ne pas disposer d'un historique complet. Dans ce cas, les données "manquantes" sont représentées par "NaN" pour les densités histogramTimeseries et par null pour les 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 (le CLS utilise des chaînes, même si elles ressemblent à des nombres).
Visualiser les données
Vous vous demandez peut-être pourquoi les données sont-elles façonnées de cette façon ? Il a été constaté que cela permet de tracer plus facilement des graphiques. Par exemple, voici un graphique pour les valeurs p75 de l'élément Interaction To Next Paint (INP) pour https://web.dev:
Dans ce graphique en courbes, chaque valeur sur l'axe Y est une valeur p75 de la série temporelle p75s, et l'axe des x correspond à la durée, définie comme lastDate pour chaque période de collecte.
Voici un graphique de séries temporelles des bins d'histogramme (appelé graphique à trois classes), car ces histogrammes comportent trois bins.
L'axe des abscisses (x) correspond à la valeur lastDate de chaque période de collecte. Toutefois, cette fois-ci, l'axe des ordonnées représente le pourcentage de chargements de page qui se situe dans une plage spécifique pour la métrique INP. Il est représenté sous la forme d'un graphique à barres empilées. Le graphique p75 offre un aperçu rapide. Dans un même 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 répartition 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 à trois classes montre que pour une petite fraction de chargements de page, l'INP était en fait faible. Dans les deux graphiques, il est relativement facile de déduire qu'une régression des performances a commencé vers la fin du mois d'octobre et a été corrigée à la mi-novembre.
Pour générer vous-même ces graphiques, nous avons créé un exemple de Colab. Un Colab, ou "Colaboratory", vous permet d'écrire et d'exécuter du code Python depuis votre navigateur. Le colab sur l'API CrUX History (source) utilise Python pour appeler l'API et représenter les données sous forme de graphique.
Ce Colab vous permet de créer des graphiques P75, des graphiques tri-bin, 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 l'utiliser, mais vous pouvez certainement regarder le code Python et le transformer en quelque chose d'incroyable ! Profitez-en et n'hésitez pas à nous faire part de vos commentaires !
Bien sûr, vous n'êtes pas limité à Colab ou Python, et 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 à l'aide de n'importe quelle technologie.
Conclusion
Avant l'introduction du point de terminaison de l'API CrUX History, les propriétaires de sites étaient limités dans les informations historiques qu'ils pouvaient obtenir de CrUX. Les données mensuelles au niveau de l'origine étaient disponibles à l'aide de BigQuery et du tableau de bord CrUX, mais les données hebdomadaires et les données historiques au niveau de la page n'étaient pas disponibles. Les propriétaires de sites pouvaient enregistrer ces données eux-mêmes à l'aide de l'API quotidienne, mais cette nécessité n'a souvent été découverte qu'après une régression dans les métriques.
L'objectif de cette API CrUX History est de permettre aux propriétaires de sites de mieux comprendre l'évolution des métriques de leur site et de l'utiliser comme outil de diagnostic pour identifier les éventuels problèmes. Si vous utilisez la nouvelle API, vos commentaires sont les bienvenus dans le groupe Google consacré au rapport d'expérience utilisateur Chrome (Discussions).
Remerciements
Image héros de Dave Harring sur Unsplash