במדריך הזה נסביר על נקודת הקצה 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. כלומר, בתקופה הזו של איסוף הנתונים, 75% מחוויית המשתמשים היו עם LCP של פחות מ-1,377 אלפיות השנייה, ו-25% מחוויית המשתמשים היו עם LCP של יותר מ-1,377 אלפיות השנייה.
בדוגמה מפורטים רק 6 רשומות של סדרות זמן ותקופות איסוף, אבל התשובות מה-API מספקות 25 רשומות של סדרות זמן. מאחר שתאריכי הסיום של כל תקופת איסוף הם ימי שבת שמפרידים ביניהם 7 ימים, מדובר ב-6 חודשים.
בכל תגובה נתונה, אורך סדרת הזמן של צפיפות התאים בתרשים ההיסטוגרמה ושל ערכי p75 יהיה זהה בדיוק לאורך המערך בשדה collectionPeriods: יש התאמה אחת לאחת על סמך המדד למערכים האלה.
שליחת שאילתות לנתונים ברמת הדף
בנוסף לנתונים ברמת המקור, CrUX History API מאפשר גישה לנתונים היסטוריים ברמת הדף. בעבר, הנתונים ברמת המקור היו זמינים באמצעות מערך הנתונים של CrUX ב-BigQuery (או באמצעות לוח הבקרה של CrUX), אבל הנתונים ההיסטוריים ברמת הדף היו זמינים רק אם האתרים אספו ושמרו את הנתונים בעצמם. ה-API החדש מאפשר עכשיו לגשת לנתונים ההיסטוריים האלה ברמת הדף.
אפשר לשלוח שאילתה לגבי הנתונים ברמת הדף באותו אופן, אבל להשתמש ב-url במקום ב-origin בתוכן המטען:
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 לכל תקופת איסוף.
זהו תרשים של סדרת הזמן של קטגוריות ההיסטוגרמה – שנקרא תרשים 'שלוש קטגוריות' – כי להיסטוגרמות האלה יש שלוש קטגוריות.
ציר ה-x מוגדר כ-lastDate לכל תקופת איסוף. הפעם, עם זאת, ציר ה-Y מייצג את אחוז טעינות הדפים שנכללות בטווח ספציפי של מדד INP, שמוצג באמצעות תרשים עמודות מוערם. תרשים p75 מספק סקירה כללית מהירה, וקל יחסית להוסיף כמה מדדים לתרשים אחד או להציג קווים גם ל-PHONE וגם ל-DESKTOP. תרשים 3-הקטגוריות מאפשר לכם להבין את ההתפלגות של ערכי המדדים שנמדדו בכל תקופת איסוף.
לדוגמה, למרות שבתרשים p75 מוצג שהערכים של INP באתר https://web.dev היו כמעט מקובלים במהלך תקופת המדידה, בתרשים של 3 קטגוריות מוצג שבחלק קטן מהטעינות של הדפים, הערך של 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