In deze handleiding wordt het Chrome UX Report (CrUX) History API- eindpunt geïntroduceerd, dat tijdreeksen van webprestatiegegevens biedt. Deze gegevens worden wekelijks bijgewerkt en laten u ongeveer zes maanden aan geschiedenis zien, met 25 gegevenspunten verspreid over een week.
Bij gebruik met de dagelijkse updates van het oorspronkelijke CrUX API- eindpunt kunt u nu snel zowel de meest recente gegevens zien als wat er eerder is gebeurd, waardoor dit een krachtig hulpmiddel is om webpagina-veranderingen in de loop van de tijd te zien.
Vraag de dagelijkse Crux API op
Om samen te vatten uit een eerder artikel over de CrUX API : u kunt op deze manier een momentopname krijgen van de veldgegevens voor een bepaalde herkomst:
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 }
}
}
}
Deze momentopname bevat histogramdichtheidswaarden en percentielwaarden voor een bepaalde verzamelperiode van 28 dagen, in dit geval van 27 december 2022 tot 23 januari 2023.
Vraag de Crux History API op
Als u het geschiedeniseindpunt wilt aanroepen, wijzigt u queryRecord in de URL in queryHistoryRecord in de curl opdracht. Het gebruik van dezelfde Crux API-sleutel als voor de vorige aanroep zal werken.
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"}'
De algemene vorm van een reactie is vergelijkbaar, maar er zijn veel meer gegevens! In plaats van één enkel gegevenspunt zijn er nu tijdreeksen voor de velden die het 75e percentiel (p75) en de histogramdichtheidswaarden bevatten.
{
"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 }
}
]
}
}
In dit voorbeeld is de tijdreeks densities voor de periode van 0 tot 2500 ms van de metriek Largest Contentful Paint (LCP) [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Elk van deze dichtheden werd waargenomen tijdens de overeenkomstige collectionPeriods invoer. De vijfde dichtheid, 0,9183, was bijvoorbeeld de dichtheid voor de vijfde verzamelperiode, eindigend op 3 september 2022, en 0,9187 was de dichtheid in de periode die eindigde in de week daarna.
Met andere woorden: bij het interpreteren van de laatste tijdreeksitems in het voorbeeld voor https://web.dev bleek dat van 14 augustus 2022 tot 10 september 2022 91,87% van de paginaladingen LCP-waarden had die kleiner waren dan 2500 ms, 5,27 % had waarden tussen 2500 ms en 4000 ms, en 2,85% had waarden groter dan 4000 ms.
Op dezelfde manier is er een tijdreeks voor de p75-waarden: de LCP p75 voor 14 augustus 2022 tot 10 september 2022 was 1377 . Dit betekent dat voor deze verzamelperiode 75% van de gebruikerservaringen een LCP van minder dan 1377 ms had, en 25% van de gebruikerservaringen een LCP van meer dan 1377 ms.
Hoewel in het voorbeeld slechts zes tijdreeksgegevens en verzamelperioden worden vermeld, bieden de antwoorden van de API 25 tijdreeksgegevens; aangezien de einddata voor elk van deze ophaalperiodes zaterdagen zijn met een tussenpoos van 7 dagen, bestrijkt dit 6 maanden.
Bij elk gegeven antwoord zal de lengte van de tijdreeksen voor de dichtheden van de histogrambins en voor p75-waarden precies hetzelfde zijn als de lengte van de array in het veld collectionPeriods : er is een één-op-één-correspondentie gebaseerd op de index in deze arrays.
Gegevens op paginaniveau opvragen
Naast gegevens op oorsprongsniveau biedt de CrUX History API toegang tot historische gegevens op paginaniveau. Hoewel de gegevens op herkomstniveau voorheen beschikbaar waren via de CrUX-dataset op BigQuery (of via het CrUX Dashboard ), waren de historische gegevens op paginaniveau alleen beschikbaar als sites de gegevens zelf verzamelden en opsloegen. De nieuwe API ontgrendelt nu die historische gegevens op paginaniveau.
De gegevens op paginaniveau kunnen op dezelfde manier worden opgevraagd, maar dan met behulp van url in plaats van origin in de payload:
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/"}'
Historische gegevens op paginaniveau (en herkomstniveau) zijn onderworpen aan dezelfde geschiktheidsvereisten als de rest van CrUX, en daarom hebben met name pagina's mogelijk geen volledig historisch record. In deze gevallen worden de "ontbrekende" gegevens weergegeven door "NaN" voor de histogramTimeseries dichtheden en null voor de percentilesTimeseries . De reden voor het verschil is dat de histogramdichtheden altijd getallen zijn, terwijl de percentielen getallen of tekenreeksen kunnen zijn (CLS gebruikt tekenreeksen, zelfs als ze op getallen lijken).
Visualiseer de gegevens
Je kunt je dus afvragen: waarom worden de gegevens op deze manier gevormd? Het bleek dat dit het gemakkelijker maakt om grafieken te plotten. Hier is bijvoorbeeld een grafiek voor de p75-waarden voor Interaction To Next Paint (INP) voor https://web.dev :
In dit lijndiagram is elke waarde op de y-as een p75-waarde uit de p75s tijdreeks, en is de x-as de tijd, die is ingesteld als de lastDate voor elke verzamelperiode.
Hier is een grafiek voor de tijdreeksen van de histogrambins, ook wel een tri-bindiagram genoemd, omdat deze histogrammen drie bins hebben.
De x-as wordt ingesteld als de lastDate voor elke verzamelperiode. Deze keer is de y-as echter het percentage paginaladingen dat binnen een specifiek bereik voor de INP-statistiek valt, weergegeven in een gestapeld staafdiagram. Het p75-diagram biedt een snel overzicht en binnen één diagram is het relatief eenvoudig om meerdere statistieken toe te voegen of regels weer te geven voor zowel PHONE als DESKTOP . Het tri-bin-diagram geeft een idee van de verdeling van de metrische waarden die tijdens elke verzamelperiode zijn gemeten.
Hoewel het p75-diagram bijvoorbeeld suggereert dat https://web.dev bijna acceptabele INP-waarden had tijdens de observatieperiode, laat het tri-bin-diagram zien dat voor een klein deel van de geladen pagina's de INP feitelijk slecht was. In beide grafieken is het relatief eenvoudig te concluderen dat er sprake was van een prestatieregressie die eind oktober begon en medio november was verholpen.
Om zelf zulke grafieken te genereren hebben wij een voorbeeld Colab gemaakt. Met een Colab, of 'Colaboratory', kun je Python vanuit je browser schrijven en uitvoeren. De CrUX History API Colab ( bron ) gebruikt Python om de API aan te roepen en de gegevens in kaart te brengen.
Met dit Colab kun je p75-diagrammen en tri-bin-diagrammen maken, gegevens in tabelvorm opvragen en het verzoek- en antwoordpaar voor de CrUX API bekijken door een kort formulier in te vullen. Je hoeft geen programmeur te zijn om dit te gebruiken, maar je kunt zeker naar de Python-code kijken en deze omzetten in iets geweldigs! Veel plezier en aarzel niet om feedback te geven op wat je vindt!
Natuurlijk ben je niet beperkt tot Colab of Python en dit is slechts één voorbeeld van hoe je deze nieuwe API kunt gebruiken. Omdat het een JSON-gebaseerd HTTP-eindpunt is, kan de API vanuit elke technologie worden opgevraagd.
Conclusie
Vóór de introductie van het CrUX History API-eindpunt waren site-eigenaren beperkt in de historische informatie die ze uit CrUX konden verkrijgen. Er waren maandelijkse gegevens op herkomstniveau beschikbaar via BigQuery en het CrUX Dashboard, maar er waren geen wekelijkse gegevens beschikbaar en ook geen historische gegevens op paginaniveau. Site-eigenaren konden deze gegevens zelf vastleggen met behulp van de dagelijkse API, maar vaak werd de noodzaak daartoe pas ontdekt na een regressie in de statistieken.
De hoop met de introductie van deze CrUX History API is dat site-eigenaren hierdoor een beter inzicht krijgen in hun veranderende sitestatistieken, en dat het een diagnostisch hulpmiddel zal zijn voor wanneer zich problemen voordoen. Als u de nieuwe API gebruikt, is feedback welkom in de Google-groep Chrome UX Report (Discussions) .
Dankbetuigingen
Hero-afbeelding door Dave Herring op Unsplash