CrUX History API מאפשרת גישה לזמן אחזור קצר לנתונים היסטוריים של חוויית משתמש אמיתית למשך שישה חודשים ברמת הפירוט של הדף והמקור.
תרחיש נפוץ
ה-CrUX History API מאפשר להריץ שאילתות על מדדים היסטוריים של חוויית משתמש ב-URI ספציפי, כמו 'קבלת המגמות ההיסטוריות של חוויית המשתמש במקור בhttps://example.com
'.
המבנה של History API זהה לזה של ה-CrUX API היומי, אבל הערכים מצוינים במערך, והמפתחות מסומנים בשמות רבים (לדוגמה, histogramTimeseries
במקום histogram
, או p75s
במקום p75
).
מפתח API של CrUX
בדומה ל-API היומי, גם השימוש ב-CrUX History API מחייב מפתח Google Cloud API. אפשר להשתמש באותו מפתח עבור ה-API היומי וה-היסטוריה.
אפשר ליצור אחד בדף Credentials ולהקצות אותו לשימוש ב-Chrome UX Report API
.
אחרי שתיצרו מפתח API, האפליקציה שלכם תוכל לצרף את פרמטר השאילתה key=[YOUR_API_KEY]
לכל כתובות ה-URL של הבקשות. ראו שאילתות לדוגמה.
מפתח ה-API בטוח להטמעה בכתובות URL; אין צורך בקידוד.
מודל נתונים
בקטע הזה מפורט מבנה הנתונים בבקשות ובתגובות.
הקלטה
פרט מידע מסוים על דף או אתר. רשומה יכולה לכלול נתונים ספציפיים למזהה ולשילוב ספציפי של מאפיינים. רשומה יכולה להכיל נתונים של מדד אחד או יותר.
מזהים
המזהים מציינים אילו רשומות צריך לחפש. ב-CrUX המזהים האלה הם דפי אינטרנט ואתרים.
מקור
כשהמזהה הוא מקור, כל הנתונים הקיימים עבור כל הדפים במקור הזה נצברים יחד. לדוגמה, נניח שבמקור http://www.example.com
היו דפים כפי שהוגדרו על ידי ה-sitemap הזה:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
כלומר, כשמריצים שאילתות בדוח חוויית המשתמש ב-Chrome שהמקור שלו הוא http://www.example.com
, יוחזרו נתונים עבור http://www.example.com/
, http://www.example.com/foo.html
ו-http://www.example.com/bar.html
יחד, כי אלה כל הדפים שמשויכים למקור הזה.
כתובות URL
כאשר המזהה הוא כתובת אתר, רק נתונים עבור כתובת האתר הספציפית הזו יוחזרו. חיפוש חוזר ל-Sitemap של המקור http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
אם המזהה מוגדר ככתובת URL עם הערך http://www.example.com/foo.html
, יוחזרו רק הנתונים של הדף הזה.
מאפיינים
המאפיינים מזהים קבוצה ספציפית של נתונים שמצוינת לגביהם רשומה. לדוגמה, גורם צורה של PHONE
מציין שהרשומה מכילה מידע על טעינות שבוצעו במכשיר נייד.
ה-CrUX History API זמין רק לפי מאפיין של גורם צורה. זוהי קבוצה כללית של מכשירים שמפוצלת ל-PHONE
, ל-TABLET
ול-DESKTOP
.
המדד
אנחנו מדווחים על מדדים בזמנים של צבירת נתונים סטטיסטיים, כמו היסטוגרמות, אחוזים ושברים.
היסטוגרמות
כאשר מדדים מבוטאים במערך היסטוגרמה, כל ערך פעמים מייצג את אחוז טעינות הדף שעבורו המדד נכלל במרווח, באופן יחסי לכולם. הנקודות על הגרף מוצגות לפי הסדר של תאריכי האיסוף שהוחזרו על ידי ה-API. הנקודה הראשונה היא התקופה המוקדמת ביותר והנקודה האחרונה היא תקופת האיסוף האחרונה.
היסטוגרמה פשוטה של שלוש בנות עבור מדד לדוגמה נראית כך:
{
"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]
}
],
}
הנתונים האלו מראים שב-91.90% מטעינות הדפים היה ערך המדד לדוגמה בין 0 אלפיות השנייה ל-2,500 אלפיות השנייה בתקופת האיסוף הראשונה בהיסטוריה, ולאחר מכן 92.03%, 91.94%... יחידות המדד לא נכללות בהיסטוגרמה הזו. במקרה הזה נניח אלפיות השנייה.
בנוסף, ב-5.21% מטעינות הדפים היה ערך המדד לדוגמה בין 2,500 אלפיות השנייה ל-4,000 אלפיות השנייה בתקופת האיסוף הראשונה בהיסטוריה. ב-2.88% מטעינות הדפים נרשמה ערך של יותר מ-4,000 אלפיות השנייה בהיסטוריה.
אחוזונים
מדדים עשויים גם לכלול זמנים של אחוזונים, שיכולים להיות שימושיים לניתוח נוסף.
הנקודות על הגרף מוצגות לפי הסדר של תאריכי האיסוף שהוחזרו על ידי ה-API. הנקודה הראשונה היא התקופה המוקדמת ביותר והנקודה האחרונה היא תקופת האיסוף האחרונה.
{
"percentilesTimeseries": {
"p75s": [1362, 1352, 1344, 1356, 1366, 1377]
},
}
האחוזונים האלה יכולים להציג ערכים של מדד ספציפי באחוזון הנתון של אותו מדד. הם מבוססים על כל הנתונים הזמינים ולא על הנתונים המגובים הסופיים, כך שהם לא בהכרח תואמים לאחוזון אינטרפולטיבי שמבוסס על ההיסטוגרמה המקשורה הסופית.
שברים
הערכים יכולים לבטא את הערכים כזמנים של שברים מתויגים. כל תווית מתארת טעינת דף בדרך מסוימת. הנקודות על הגרף מוצגות לפי הסדר של תאריכי האיסוף שהוחזרו על ידי ה-API. הנקודה הראשונה היא התקופה המוקדמת ביותר והנקודה האחרונה היא תקופת האיסוף האחרונה.
דוגמה:
{
"fractionTimeseries": {
"desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
"phone": {"fractions": [0.6295, 0.7544, 0.8288]},
"tablet": {"fractions": [0.051, 0.0341, 0.029]}
}
}
בדוגמה הזו, נקודת הנתונים העדכנית ביותר מראה ש-14.21% מטעינות הדפים הגיעו ממחשבים ו-82.88% הגיעו מטלפונים.
סוגי ערכים של מדדים
מכיוון ש-CrUX History API משתמשים באותם סוגי מדדים, ניתן לעיין במסמכי התיעוד היומיים של סוגי ערכים של CrUX API לקבלת פרטים נוספים.
דרישות הסף של המדד
בהתאם לקריטריונים לזכאות, יכול להיות שכתובת URL או מקור יהיו כשירים רק לחלק מתקופות האיסוף שכפופות ל-CrUX History API. במקרים כאלה, ה-CrUX History API יחזיר "NaN"
עבור הדחיסות histogramTimeseries
ו-null
עבור ה-percentilesTimeseries
עבור תקופות האיסוף שאין בהן נתונים מתאימים. הסיבה להבדל היא שצפיפות ההיסטוגרמות היא תמיד מספרים, בעוד שהאחוזונים יכולים להיות מספרים או מחרוזות (ב-CLS נעשה שימוש במחרוזות, גם אם הם נראים כמו מספרים).
לדוגמה, אם בתקופה השנייה לא היו נתונים כשירים, יוצג המצב הבא:
{
"histogramTimeseries": [
{
"start": 0,
"end": 2500,
"densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
},
{
"start": 2500,
"end": 4000,
"densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
},
{
"start": 4000,
"densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
}
],
"percentilesTimeseries": {
"p75s": [1362, null, 1344, 1356, 1366, 1377]
},
}
אם יש כתובות URL או מקורות שלא עומדים בדרישות הסף לאורך זמן, יכול להיות שתבחינו בהרבה רשומות חסרות.
תקופות איסוף
ה-CrUX History API מכיל אובייקט collectionPeriods
עם מערך של השדות firstDate
ו-endDate
שמייצגים את תאריכי ההתחלה והסיום של כל חלון צבירה. למשל:
"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 }
}
]
תקופות האיסוף האלה מסודרות בסדר עולה ומייצגות את טווח התאריכים של כל אחת מהנקודות בקטעים האחרים של התשובה.
ה-History API מתעדכן מדי יום שני ומכיל נתונים עד יום שבת הקודם (בהתאם לפרק הזמן הרגיל של יומיים). הוא מכיל נתונים מ-25 השבועות הקודמים — תקופת איסוף אחת בשבוע.
כל תקופת איסוף כוללת נתונים נצברים מ-28 הימים האחרונים, ולכן תקופות האיסוף הן לפי שבוע. פירוש הדבר הוא שתקופות האיסוף חופפות. הם דומים לממוצע נע של נתונים, כאשר בכל תקופה עוקבת נכללים נתונים משלושה שבועות, ושבוע אחד שונה מהם.
שאילתות לדוגמה
השאילתות נשלחות כאובייקטי JSON באמצעות בקשת POST ל-https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]"
, עם נתוני שאילתה כאובייקט JSON בגוף ה-POST.
שימו לב לשימוש ב-queryHistoryRecord
שמחליף את queryRecord
של ממשק ה-API היומי של CrUX.
גוף לדוגמה:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
לדוגמה, אפשר לקרוא לפונקציה הזו מ-curl
באמצעות שורת הפקודה הבאה (מחליפה את API_KEY
במפתח):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
נתונים ברמת הדף זמינים דרך ה-API על ידי העברת נכס url
בשאילתה במקום origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
אם המאפיין metrics
לא מוגדר, יוחזרו כל המדדים הזמינים:
cumulative_layout_shift
first_contentful_paint
first_input_delay
interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(מדווח רק אם לא צויןformFactor
בבקשה)
אם לא תספקו ערך של formFactor
, הערכים יצטברו בכל גורמי הצורה.
אפשר לעיין במדריך לשימוש ב-CrUX History API לשאילתות נוספות.
צינור נתונים
מערך הנתונים של CrUX מעובד באמצעות צינור עיבוד נתונים לאיחוד, צבירה וסינון של הנתונים לפני שהם הופכים לזמינים דרך ה-API.
הממוצע הנע
הנתונים בדוח חוויית המשתמש ב-Chrome הם ממוצע נע של מדדים נצברים במשך 28 ימים. כלומר, הנתונים המוצגים בדוח חוויית המשתמש ב-Chrome בכל זמן נתון הם למעשה נתונים מ-28 הימים האחרונים.
History API מכיל מספר תקופות איסוף, שכל אחת מ-28 הימים האלה. כל תקופת איסוף כוללת נתונים נצברים מ-28 הימים האחרונים, ולכן תקופות האיסוף הן לפי שבוע. פירוש הדבר הוא שתקופות האיסוף חופפות. הם דומים לממוצע נע של נתונים, כאשר בכל תקופה עוקבת נכללים נתונים משלושה שבועות, ושבוע אחד שונה מהם.
עדכונים שבועיים
ה-History API מתעדכן מדי יום שני בסביבות השעה 04:00 UTC ומכיל נתונים עד ליום שבת הקודם (בהתאם לפרק הזמן הרגיל של יומיים). הדוח כולל נתונים מ-25 השבועות האחרונים (בערך 6 חודשים), תקופת איסוף אחת בשבוע.
אין הסכם רמת שירות (SLA) למועדי עדכון. השירות מתבצע על בסיס יומי, ככל שניתן.
סכימה
ל-CrUX History API יש נקודת קצה אחת (endpoint) אחת שמקבלת בקשות HTTP מסוג POST
. ה-API מחזיר record
שמכיל metrics
אחד או יותר, בהתאם לנתוני הביצועים לגבי המקור או הדף המבוקשים.
בקשת HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord
בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.
גוף הבקשה
ב-CrUX History API נעשה שימוש באותם גופי בקשות שבהם נעשה שימוש בממשק ה-API היומי של CrUX, פרט לכך שהוא לא תומך בשדה הבקשה effectiveConnectionType
.
לדוגמה, כדי לבקש את ערכי ה-LCP במחשב בשביל דף הבית של web.dev:
{
"origin": "https://web.dev/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
גוף התשובה
בקשות שבוצעו בהצלחה מחזירות תגובות עם אובייקט record
ו-urlNormalizationDetails
במבנה הבא:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
לדוגמה, התגובה לגוף הבקשה בבקשה הקודמת יכולה להיות:
{
"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 }
}, {
...
}
]
}
}
מפתח
Key
מגדיר את כל המאפיינים שמזהים את הרשומה הזו כייחודיים.
{
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
שדות | |
---|---|
formFactor |
גורם הצורה הוא סוג המכשיר שבו כל המשתמשים השתמשו כדי לגשת לאתר עבור הרשומה הזו. אם לא צוין גורם צורה, יוחזרו נתונים נצברים מכל גורמי הצורה. |
שדה איחוד url_ . תבנית ה-URL היא כתובת ה-URL שעליה הרשומה חלה. url_ יכול להיות רק אחד מהבאים: |
|
origin |
'מקור' מציין את המקור שעבורו הרשומה הזו מיועדת. הערה: כשמציינים מקור, הנתונים של טעינות מתחת למקור הזה לגבי כל הדפים נצברים לנתונים של חוויית המשתמש ברמת המקור. |
url |
הערה: כשמציינים |
מדדים
metric
הוא קבוצה של נתונים על חוויית המשתמש למדד יחיד של ביצועים באינטרנט, כמו הצגת תוכן ראשוני (FCP). היא מכילה סיכום של ההיסטוגרמה של השימוש ב-Chrome בעולם האמיתי כסדרה של bins
.
{
"histogramTimeseries": [
{
object (Bin)
}
],
"percentilesTimeseries": {
object (Percentiles)
}
}
או
"fractionTimeseries": {
object (Fractions)
}
שדות | |
---|---|
histogramTimeseries[] |
ההיסטוגרמה של חוויות המשתמש למדד. היסטוגרמה של לוחות הזמנים תכלול לפחות סל אחד והצפיפות של כל הסלים תסתכם ב- ~1. ערכים חסרים לגבי תקופת איסוף ספציפית יסומנו כ- |
percentilesTimeseries |
אחוזים שימושיים נפוצים של המדד. סוג הערך של האחוזים יהיה זהה לסוגי הערכים שניתנו עבור סלי ההיסטוגרמה. ערכים חסרים לגבי תקופת איסוף ספציפית יסומנו כ- |
fractionTimeseries |
האובייקט הזה מכיל זמני צירים של שברים מתויגים, שמסתכמים בערך אחד לכל רשומה. שברים מעוגלים ל-4 ספרות אחרי הנקודה העשרונית. ערכים חסרים מבוטאים כ-'NaN' בכל השברים. |
סל
bin
הוא חלק נפרד מנתונים שנצברו מתחילתו ועד סופו, או אם לא ניתן לו סיום מתחילתו ועד סופו החיובי.
ערכי ההתחלה והסיום של סל מצוינים בסוג הערך של המדד שהוא מייצג. לדוגמה, המהירות שבה נטען רכיב התוכן הראשון נמדדת באלפיות השנייה ונחשפת כ-ints, ולכן הסלים המטריים שלו ישתמשו ב-int32 בסוגי ההתחלה והסיום. עם זאת, שינוי פריסה מצטבר נמדד בשברים עשרוניים ללא יחידה והוא חשוף כמחרוזת עשרונית המקודדת כמחרוזת, ולכן סלי המדדים שלו ישתמשו במחרוזות עבור סוג הערך שלו.
{
"start": value,
"end": value,
"densities": [number, number, number...etc.]
}
שדות | |
---|---|
start |
Start היא תחילת סל הנתונים. |
end |
End הוא הסוף של סל הנתונים. אם הפרמטר end_end לא מאוכלס, אז לסל אין קצה והוא תקף מהתחלה ועד ל-inf. |
densities |
זמני צירים של שיעור המשתמשים שחוו את הערך של bin זה עבור המדד הנתון. ערכי הצפיפות יעוגלו ל-4 ספרות אחרי הנקודה העשרונית. |
אחוזונים
Percentiles
מכיל ערכים סינתטיים של מדד באחוזון סטטיסטי נתון. המדדים האלה משמשים להערכת הערך של מדד, כפי שאחוז המשתמשים רואים אותו מתוך מספר המשתמשים הכולל.
{
"P75": value
}
שדות | |
---|---|
p75s |
זמני קריאה של הערכים ש-75% מטעינות הדפים הציגו את הערך הנתון בערך הזה או פחות ממנו. |
שברים
Fractions
מכיל זמני צירים של שברים מתויגים שמסתכמים ב-~1, לכל ערך.
כל תווית מתארת טעינת דף בצורה מסוימת, כך שמדדים המיוצגים באופן זה נוצרים כערכים נפרדים במקום ערכים מספריים, ושברים משקפים את התדירות שבה נמדד ערך ייחודי מסוים.
{
"label_1": { "fractions": array[fraction]},
"label_1": { "fractions": array[fraction]},
...
"label_n": { "fractions": array[fraction]}
}
בדומה לערכי הצפיפות בעמודות ההיסטוגרמה, כל fraction
הוא מספר 0.0 <= value <= 1.0
, והסכום הכולל שלהם הוא ~1.0. אם המדד לא זמין לתקופת איסוף מסוימת, הערך המתאים יהיה "NaN" בכל המערכים של השברים.
שדות | |
---|---|
p75s |
זמני קריאה של הערכים ש-75% מטעינות הדפים חוו את הערך הנתון בערך הזה או נמוך ממנו. |
UrlNormalization
אובייקט שמייצג את פעולות הנירמול שבוצעו כדי לנרמל כתובת URL על מנת להשיג סיכוי גבוה יותר לחיפוש תקין. מדובר בשינויים אוטומטיים פשוטים שמתבצעים כשמחפשים את השדה url_pattern
שצוין. פעולות מורכבות כמו הפניות לכתובות אחרות לא מטופלות.
{
"originalUrl": string,
"normalizedUrl": string
}
שדות | |
---|---|
originalUrl |
כתובת ה-URL המקורית שנשלחה לפני ביצוע פעולות נירמול. |
normalizedUrl |
כתובת ה-URL אחרי פעולות נירמול. זוהי כתובת URL חוקית של חוויית משתמש שניתן לחפש אותה באופן סביר. |
הגבלות קצב של יצירת בקשות
ה-CrUX History API חולק את אותה מגבלה עם CrUX API ל-150 שאילתות לדקה לכל פרויקט ב-Google Cloud בכל אחד מה-APIs, שמוצעים ללא תשלום. במסוף Google Cloud תוכלו לראות את המגבלה הזו ואת השימוש הנוכחי שלכם. המכסה הנדיבה הזו אמורה להספיק לרוב המכריע של תרחישי השימוש, ואי אפשר לשלם על מכסה מוגדלת.