במדריך הזה נסביר על נקודת הקצה History API של דוח חוויית המשתמש ב-Chrome (CrUX), שמספקת סדרות זמן של נתוני ביצועים באינטרנט. הנתונים האלה מתעדכנים מדי שבוע ומאפשרים לכם לראות היסטוריה של כ-6 חודשים, עם 25 נקודות נתונים במרווח של שבוע.
כשמשתמשים ב-CrUX API יחד עם העדכונים היומיים מנקודת הקצה המקורית, אפשר לראות במהירות גם את הנתונים העדכניים ביותר וגם את מה שקרה בעבר. כך, הכלי הזה הופך לכלי יעיל מאוד לראות שינויים בדפי אינטרנט לאורך זמן.
ניסיון ב-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 אלפיות השנייה של המדד Largest Contentful Paint (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,500ms, ל-5.27% היו ערכים בין 2,500ms ל-4,000ms ול-2.85% היו ערכים גבוהים מ-4,000ms.
באופן דומה, יש סדרה כרונולוגית של ערכי p75: הערך של p75 של LCP מ-14 באוגוסט 2022 עד 10 בספטמבר 2022 היה 1377. פירוש הדבר הוא שבתקופת האיסוף הזו, ערך ה-LCP ב-75% מחוויות המשתמש היה פחות מ-1,377 אלפיות השנייה, וב-25% מחוויות המשתמש היה ערך LCP גדול מ-1,377 אלפיות השנייה.
בדוגמה מפורטות רק 6 רשומות של סדרות זמנים ותקופות של איסוף, אבל התשובות מה-API כוללות 25 רשומות של סדרות זמנים. בגלל שתאריכי הסיום של כל אחת מהתקופות האלה הם ימי שבת בהפרש של 7 ימים, והתשובות האלה כוללות 6 חודשים.
בכל תגובה נתונה, אורך סדרת הזמן של צפיפות התאים בתרשים ההיסטוגרמה ושל ערכי 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 של זמן אינטראקציה עד התוכן הבא (INP) באתר https://web.dev:
בתרשים הקו הזה, כל ערך בציר ה-Y הוא ערך p75 מסדרת הזמנים p75s, וציר ה-X הוא הזמן, שמוגדר כ-lastDate לכל תקופת איסוף.
הנה תרשים של סדרת זמנים של היסטוגרמה bin, שנקראת תרשים Tri-bin, כי בהיסטוגרמות האלה יש שלושה פחים.
ציר ה-x מוגדר כ-lastDate לכל תקופת איסוף. הפעם, עם זאת, ציר ה-Y מייצג את אחוז טעינות הדפים שנכללות בטווח ספציפי של מדד INP, שמוצג באמצעות תרשים עמודות מוערם. תרשים p75 מספק סקירה כללית מהירה, וקל יחסית להוסיף כמה מדדים לתרשים אחד או להציג קווים גם ל-PHONE וגם ל-DESKTOP. תרשים של 3 קטגוריות מאפשר לכם להבין את ההתפלגות של ערכי המדדים שנמדדו בכל תקופת איסוף.
לדוגמה, למרות שתרשים p75 מצביע על כך שב-https://web.dev היו ערכי INP כמעט מקובלים במהלך תקופת התצפית, התרשים ה-Tri-bin מראה שבחלק קטן מטעינות הדפים, ה-INP היה נמוך למעשה. בשני התרשימים קל יחסית להסיק שהייתה רגרסיה של ביצועים שהתחילו לקראת סוף אוקטובר, ותוקנה עד אמצע נובמבר.
כדי ליצור תרשימים כאלה בעצמכם, יצרנו Colab לדוגמה. Colab, או Colaboratory, הוא מוצר שמאפשר לכתוב קוד Python ולהריץ אותו בדפדפן. ב-CrUX History API Colab (מקור) נעשה שימוש ב-Python כדי לבצע קריאות ל-API ולתעד את הנתונים בתרשים.
בעזרת ה-Colab הזה תוכלו ליצור תרשימים של p75, תרשימים של 3 קטגוריות, לקבל נתונים בצורת טבלה ולראות את הצמד של הבקשה והתגובה ל-CrUX API, על ידי מילוי טופס קצר. אתם לא צריכים להיות מתכנתים כדי להשתמש בזה, אבל אתם בהחלט יכולים לעיין בקוד Python ולשנות אותו למשהו מדהים! תהנו, ואל תהססו לשלוח משוב על מה שמצאתם.
כמובן שאתם לא מוגבלים ל-Colab או ל-Python, וזו רק דוגמה אחת לאופן השימוש ב-API החדש הזה. כנקודה קצה מסוג HTTP שמבוססת על JSON, אפשר לשלוח שאילתות ל-API מכל טכנולוגיה.
סיכום
לפני ההשקה של נקודת הקצה של CrUX History API, בעלי אתרים היו מוגבלים במידע ההיסטורי שהם היו יכולים לקבל מ-CrUX. נתונים חודשיים ברמת המקור היו זמינים באמצעות BigQuery ולוח הבקרה של CrUX, אבל נתונים שבועיים לא היו זמינים, וגם לא נתונים היסטוריים ברמת הדף. בעלי אתרים יכלו לתעד את הנתונים האלה בעצמם באמצעות ה-API היומי, אבל לרוב הצורך בכך התגלה רק אחרי ירידה במדדים.
אנחנו מקווים שהשקת CrUX History API תאפשר לבעלי אתרים להבין טוב יותר את המדדים המשתנים של האתר שלהם, וככלי אבחון במקרה של בעיות. אם אתם משתמשים ב-API החדש, נשמח לקבל מכם משוב בקבוצת Google Chrome UX Report (Discussions).
תודות
התמונה הראשית (Hero) של Dave Herring ב-Unsplash