במדריך הזה מוצגת נקודת הקצה (Chrome UX Report (CrUX) History API, שמספקת נתונים על ביצועי אתרים בציר הזמן. הנתונים האלה מתעדכנים מדי שבוע ומאפשרים לכם לראות היסטוריה של שישה חודשים, עם 25 נקודות נתונים שמרווחים כל שבוע.
בשילוב עם העדכונים היומיים מנקודת הקצה המקורית של CrUX API, עכשיו אפשר לראות במהירות גם את הנתונים העדכניים ביותר וגם את מה שקרה בעבר. זהו כלי שימושי מאוד להצגת שינויים בדפי אינטרנט לאורך זמן.
הרצת שאילתות ב-CrUX API היומי
לסיכום מאמר קודם בנושא CrUX API, אפשר לקבל תמונת מצב של נתוני השדות למקור מסוים באופן הבא:
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 }
}
}
}
תמונת המצב הזו כוללת ערכי צפיפות של היסטוגרמה וערכי אחוזון עבור תקופה מסוימת של 28 ימים לאיסוף נתונים. במקרה הזה, מ-27 בדצמבר 2022 עד 23 בינואר 2023.
הרצת שאילתות על CrUX History API
כדי לקרוא לנקודת הקצה של ההיסטוריה, צריך לשנות את queryRecord בכתובת ה-URL ל-queryHistoryRecord בפקודה curl. שימוש במפתח API של CrUX שבו נעשה שימוש בשיחה הקודמת יפעל.
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"}'
התגובה באופן כללי דומה, אבל יש הרבה יותר נתונים. במקום להציג נקודת נתונים אחת, עכשיו יש סדרות זמנים לשדות שמכילים את ערכי האחוזון ה-75 (p75) והצפיפות של ההיסטוגרמה.
{
"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 }
}
]
}
}
בדוגמה הזו, סדרת הזמנים של densities עבור הקטגוריה של 0 עד 2,500 אלפיות השנייה של המדד המהירות שבה נטען רכיב התוכן הכי גדול (LCP) היא [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. כל אחת מהצפיפות הזו נצפתה במהלך הרשומה המתאימה ב-collectionPeriods. לדוגמה, הצפיפות החמישית, 0.9183, הייתה הצפיפות בתקופת האיסוף החמישית, שהסתיימה ב-3 בספטמבר 2022, ו-0.9187 הייתה הצפיפות בתקופה שהסתיימה בשבוע שלאחר מכן.
במילים אחרות, בפירוש הנתונים של סדרות הזמן האחרונות בדוגמה עבור https://web.dev, נמצא כי מ-14 באוגוסט 2022 עד 10 בספטמבר 2022, ב-91.87% מטעינות הדפים היו ערכי LCP שנמוכים מ-2,500 אלפיות השנייה, ב-5.27% היו ערכים בין 2500% לבין 4,000 אלפיות שנייה ו-4,000 אלפיות שנייה מ-4,000 אלפיות שנייה.
באופן דומה, יש סדרת זמנים לערכי p75: ה-LCP p75 ל-14 באוגוסט 2022 עד 10 בספטמבר 2022 היה 1377. פירוש הדבר הוא שבתקופת האיסוף הזו, ב-75% מחוויות המשתמש היה LCP של פחות מ-1377 אלפיות השנייה, וב-25% מחוויות המשתמש היה LCP יותר מ-1377 אלפיות השנייה.
הדוגמה מפרטת רק 6 רשומות של סדרות זמנים ותקופות איסוף, אבל התשובות מה-API מספקות 25 רשומות של פעולות על ציר הזמן. מאחר שתאריכי הסיום של כל אחת מתקופות האיסוף הם ימי שבת בהפרש של 7 ימים זה מזה, מדובר ב-6 חודשים.
בכל תגובה נתונה, משך סדרת הזמן עבור הדחיסות של bin ההיסטוגרמה ושל ערכי p75 יהיה זהה בדיוק לאורך המערך בשדה collectionPeriods: יש התאמה של אחד לאחד על בסיס האינדקס למערכים האלה.
שאילתה לגבי נתונים ברמת הדף
בנוסף לנתונים ברמת המקור, CrUX History API מאפשר גישה לנתונים היסטוריים ברמת הדף. הנתונים ברמת המקור היו זמינים בעבר באמצעות מערך הנתונים של CrUX ב-BigQuery (או באמצעות מרכז הבקרה של CrUX), אבל הנתונים ההיסטוריים ברמת הדף היו זמינים רק אם האתרים אספו ואחסנו את הנתונים בעצמם. ה-API החדש מבטל את הנעילה של הנתונים ההיסטוריים ברמת הדף.
אפשר לשלוח שאילתות לגבי נתונים ברמת הדף באותו אופן, אבל משתמשים ב-url במקום ב-origin במטען הייעודי (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/"}'
נתונים היסטוריים ברמת הדף (וברמת המקור) כפופים לאותן דרישות הסף כמו בשאר השירותים של CrUX. לכן, יכול להיות שלדפים ספציפיים אין תיעוד היסטורי מלא. במקרים האלה, הנתונים ה "חסרים" ייוצגו על ידי "NaN" עבור הצפיפות histogramTimeseries ו-null עבור percentilesTimeseries. הסיבה להבדל היא שצפיפות ההיסטוגרמות היא תמיד מספרים, בעוד שהאחוזונים יכולים להיות מספרים או מחרוזות (ב-CLS נעשה שימוש במחרוזות, גם אם הם נראים כמו מספרים).
הצגה חזותית של הנתונים
אז תוכל לשאול, מדוע הנתונים מעוצבים כך? גילינו שכך קל יותר להציג גרפים. לדוגמה, כאן מופיע תרשים של ערכי p75 של Interaction To Next Paint (INP) של https://web.dev:
בתרשים הקו הזה, כל ערך בציר ה-Y הוא ערך של p75 מסדרת הזמן p75s וציר ה-X הוא הזמן, שמוגדר כ-lastDate בכל תקופת איסוף.
הנה תרשים של סדרת הזמנים של סל ההיסטוגרמה – שנקרא 'תרשים טרי-בין' – כי יש בהיסטוגרמות שלוש סלים.
ציר ה-X מוגדר כ-lastDate בכל תקופת איסוף. עם זאת, הפעם ציר ה-Y מייצג את אחוז טעינות הדף בטווח ספציפי של מדד ה-INP, והוא מוצג באמצעות תרשים עמודות מוערם. תרשים p75 מספק סקירה כללית מהירה, ובתוך תרשים יחיד קל יחסית להוסיף כמה מדדים, או להציג קווים גם של PHONE וגם של DESKTOP. תרשים המשולשים מספק מושג לגבי ההתפלגות של ערכי מדדים שנמדדים במהלך כל תקופת איסוף.
לדוגמה, אף על פי שבתרשים ה-p75 נראה שערכי INP בכתובת https://web.dev היו כמעט קבילים במהלך תקופת התצפית, התרשים המשולש מראה שבחלק קטן מטעינות הדפים, מדד ה-INP היה נמוך. בשני התרשימים, קל יחסית להסיק שהייתה רגרסיה של ביצועים שהתחילה לקראת סוף אוקטובר ותוקנה עד אמצע נובמבר.
כדי ליצור תרשימים כאלה בעצמכם, יצרנו דוגמה ל-Colab. Colab, או 'Colaboratory', מאפשר לכתוב ולהפעיל Python מתוך הדפדפן. ב-CrUX History API Colab (מקור) נעשה שימוש ב-Python כדי לבצע קריאות ל-API ולהציג תרשים של הנתונים.
ב-Colab אפשר ליצור תרשימי p75 ותרשימי תלת-ממד, לקבל נתונים בטבלאות ולראות את צמדי הבקשות והתשובות ל-CrUX API, על ידי מילוי טופס קצר. אתם לא צריכים להיות מתכנתים כדי להשתמש בזה, אבל אתם בהחלט יכולים להסתכל על קוד Python ולשנות אותו למשהו מדהים! אנחנו מזמינים אותך ליהנות מהמשוב, ונשמח לקבל משוב על מה שמוצאים.
כמובן שאתם לא מוגבלים ל-Colab או Python וזו רק דוגמה אחת לשימוש ב-API החדש הזה. כנקודת קצה מבוססת-JSON, ה-API ניתן להרצת שאילתות מכל טכנולוגיה.
סיכום
לפני שהשקנו את נקודת הקצה של CrUX History API, בעלי האתרים היו מוגבלים מבחינת המידע ההיסטורי שהם יכלו להשיג מ-CUX. נתונים חודשיים ברמת המקור היו זמינים דרך BigQuery ולוח הבקרה של CrUX, אבל הנתונים השבועיים לא היו זמינים וגם לא היו נתונים היסטוריים ברמת הדף. בעלי אתרים יכלו לתעד את הנתונים האלה בעצמם באמצעות ה-API היומי, אבל לעיתים קרובות הצורך הזה התגלה רק לאחר רגרסיה במדדים.
אנחנו מקווים ש-CrUX History API יושקו ב-CrUX History API כדי לאפשר לבעלי אתרים להבין טוב יותר את השינויים במדדי האתר, ככלי אבחון למקרים שבהם מתעוררות בעיות. אם אתם משתמשים בממשק ה-API החדש, נשמח לקבל מכם משוב בקבוצת Google של דוח חוויית המשתמש (דיונים).
אישורים
תמונה ראשית (Hero) מאת דייב הרינג ב-UnFlood