פורסם: 7 בפברואר 2023, עדכון אחרון: 11 באפריל 2025
במדריך הזה מוצגת נקודת הקצה Chrome UX Report (CrUX) History API, שמספקת נתונים של ביצועי אתרים על ציר הזמן. הנתונים האלה מתעדכנים מדי שבוע, ואפשר לראות היסטוריה של כ-6 חודשים, עם 40 נקודות נתונים במרווחים של שבוע.
כשמשתמשים בנקודת הקצה החדשה של 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. אפשר להשתמש באותו מפתח CrUX API כמו בקריאה הקודמת.
collectionPeriodCount מציין את מספר הרשומות של סדרות הזמן שיוחזרו. המספר המקסימלי הוא 40. אם לא מציינים ערך, ברירת המחדל היא 25.
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", "collectionPeriodCount": 40}'
התשובה דומה, אבל יש בה הרבה יותר נתונים. במקום נקודת נתונים אחת, יש עכשיו סדרות זמן לשדות שמכילים את האחוזון ה-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,500ms, ב-5.27% היו ערכים בין 2,500ms ל-4,000ms, וב-2.85% היו ערכים גדולים מ-4,000ms.
באופן דומה, יש סדרת זמנים לערכי p75: ערך ה-LCP p75 מ-14 באוגוסט 2022 עד 10 בספטמבר 2022 היה 1377. המשמעות היא שבמהלך תקופת האיסוף הזו, ב-75% מחוויית המשתמש נמדד LCP של פחות מ-1,377 אלפיות השנייה, וב-25% מחוויית המשתמש נמדד LCP של יותר מ-1,377 אלפיות השנייה.
בדוגמה מופיעים רק 6 ערכים של סדרות זמנים ותקופות איסוף, אבל בתגובות מ-API מופיעים כברירת מחדל 25 ערכים של סדרות זמנים, ומקסימום 40 ערכים אם מציינים את "collectionPeriodCount": 40 בבקשה. תאריכי הסיום של כל תקופת איסוף הם ימי שבת בהפרש של 7 ימים, ולכן עם "collectionPeriodCount": 40 זה מכסה 10 חודשים.
בכל תגובה נתונה, האורך של סדרת הזמן של צפיפויות תאי ההיסטוגרמה ושל ערכי p75 יהיה בדיוק כמו האורך של מערך בשדה collectionPeriods: יש התאמה של אחד לאחד על סמך האינדקס במערכים האלה.
שאילתת נתונים ברמת הדף
בנוסף לנתונים ברמת המקור, CrUX History API מאפשר גישה לנתונים היסטוריים ברמת הדף. בעבר, הנתונים ברמת המקור היו זמינים באמצעות מערך הנתונים של CrUX ב-BigQuery, אבל הנתונים ההיסטוריים ברמת הדף היו זמינים רק אם האתרים אספו ואחסנו את הנתונים בעצמם. ה-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 משתמש במחרוזות, גם אם הן נראות כמו מספרים).
המחשת הנתונים
הדרך הקלה ביותר להציג את הנתונים היא באמצעות CrUX Vis, כלי שנוצר במיוחד כדי להדגים את היכולות של CrUX History API. מידע נוסף זמין בתיעוד של CrUX Vis.
כדי ליצור תרשימים דומים בעצמכם, יצרנו דוגמה ב-Colab. Colab, או Colaboratory, הוא מוצר שמאפשר לכתוב קוד Python ולהריץ אותו בדפדפן. CrUX History API Colab (מקור) משתמש ב-Python כדי לבצע קריאות ל-API ולשרטט את הנתונים.
במחברת Colab הזו אפשר ליצור תרשימי p75, תרשימי tri-bin, לקבל נתונים בפורמט טבלאי ולראות את צמד הבקשה והתגובה של CrUX API, על ידי מילוי טופס קצר. לא צריך להיות מתכנתים כדי להשתמש בזה – אבל אתם בהחלט יכולים לעיין בקוד Python ולשנות אותו למשהו מדהים! נשמח לקבל משוב על מה שתמצאו!
כמובן שאתם לא מוגבלים ל-Colab או ל-Python, וזו רק דוגמה אחת לשימוש ב-API החדש הזה. ממשק ה-API הוא נקודת קצה של HTTP שמבוססת על JSON, ולכן אפשר לשלוח אליו שאילתות מכל טכנולוגיה.
סיכום
לפני שהשקנו את נקודת הקצה של CrUX History API, בעלי אתרים יכלו לקבל מ-CrUX רק מידע היסטורי מוגבל. נתונים חודשיים ברמת המקור היו זמינים באמצעות BigQuery, אבל נתונים שבועיים או נתונים היסטוריים ברמת הדף לא היו זמינים. בעלי אתרים יכולים לתעד את הנתונים האלה בעצמם באמצעות ה-API היומי, אבל לעיתים קרובות הצורך בנתונים האלה מתגלה רק אחרי רגרסיה במדדים.
אנחנו מקווים שה-API הזה של היסטוריית נתונים ב-CrUX יעזור לבעלי אתרים להבין טוב יותר את השינויים במדדים של האתר שלהם, ויוכל לשמש ככלי אבחון כשמתעוררות בעיות. אם אתם משתמשים ב-API החדש, אתם מוזמנים לשלוח משוב ל-קבוצת Google של דוח חוויית המשתמש של Chrome (דיונים).
תודות
תמונה ראשית (Hero) של Dave Herring ב-Unsplash