ב-CrUX API יש גישה עם זמן אחזור קצר לנתונים נצברים של חוויית משתמש אמיתיים ברמת הפירוט של הדף והמקור.
תרחיש לדוגמה נפוץ
ה-CrUX API מאפשר לשלוח שאילתות על מדדי חוויית המשתמש עבור URI ספציפי, כמו "קבלת מדדים למקור https://example.com
".
מפתח API של CrUX
כדי להשתמש ב-CrUX API, צריך להקצות מפתח API של Google Cloud לשימוש ב-Chrome UX Report API
.
קבלת מפתח API ושימוש בו
לקבלת מפתחאפשר גם ליצור כרטיס בדף פרטי כניסה.
אחרי שיש לכם מפתח API, האפליקציה יכולה לצרף את פרמטר השאילתה
key=yourAPIKey
בכל כתובות ה-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
כאשר המזהה הוא כתובת URL, יוחזרו רק הנתונים לגבי כתובת ה-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
מציין שהרשומה מכילה מידע על טעינות שבוצעו במכשיר נייד. לכל מאפיין יש מספר מסוים של ערכים, ובפירוש אי-ציון המאפיין, המשמעות היא שהמאפיין נצבר על פני כל הערכים. לדוגמה, ציון אף גורם צורה אינו מציין שהרשומה מכילה מידע על טעינות שבוצעו בגורם צורה כלשהו.
מבנה
סיווג המכשיר שמשתמש הקצה השתמש בו כדי לנווט לדף. זהו סיווג כללי של מכשירים שמפוצלים ל-PHONE
, ל-TABLET
ול-DESKTOP
.
סוג החיבור האפקטיבי
סוג החיבור האפקטיבי הוא איכות החיבור המשוערת של המכשיר כשמנווטים לדף. זוהי כיתה כללית שמחולקת ל-offline
, ל-slow-2G
, ל-2G
, ל-3G
ול-4G
.
מדד
אנחנו מדווחים על מדדים כצבירת נתונים סטטיסטיים, בהיסטוגרמות, באחוזונים ובשברים.
הערכים של הנקודות הצפה מעוגלים ל-4 ספרות אחרי הנקודה העשרונית (חשוב לשים לב שהמדדים cumulative_layout_shift
מקודדים פעמיים כמחרוזת. לכן, הם לא מתייחסים למספר צפים ומדווחים ל-2 ספרות אחרי הנקודה העשרונית).
היסטוגרמה
כאשר המדדים מבוטאים בהיסטוגרמה, אנחנו מציגים את אחוזי טעינות הדפים באתר טווחים מסוימים עבור המדד הזה.
היסטוגרמה של שלוש bin עבור מדד לדוגמה נראית כך:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
הנתונים האלה מציינים שעבור 38.18% מטעינות הדפים, המדד לדוגמה נמדד בין 0 אלפיות השנייה ל-1,000 אלפיות שנייה. יחידות המדד לא נכללות בהיסטוגרמה הזו במקרה הזה נשתמש באלפיות שנייה.
בנוסף, 49.91% מטעינות הדפים הניבו ערך בין 1,000 אלפיות השנייה ל-3,000 אלפיות שנייה, ו-11.92% היה ערך של יותר מ-3,000 אלפיות השנייה.
אחוזונים
מדדים עשויים גם לכלול אחוזונים שיכולים להיות שימושיים לניתוח נוסף. אנחנו מדווחים על ערכים של מדדים ספציפיים באחוזון הנתון לגבי אותו מדד. הם מבוססים על המערך המלא של הנתונים הזמינים ולא על הנתונים הבינאריים הסופיים, כך שהם לא בהכרח תואמים לאחוזון אינטרפולטיבי שמבוסס על ההיסטוגרמה האחרונה.
{
"percentiles": {
"p75": 2063
}
}
בדוגמה הזו, לפחות 75% מטעינות הדפים נמדדו עם ערך המדד <= 2063
.
שברים
שברים מציינים את אחוזי טעינות הדפים שניתן לתייג באופן מסוים. במקרה הזה, ערכי המדדים הם התוויות האלה.
לדוגמה, המדד form_factors
מורכב מאובייקט fractions
, שבו מפורט פירוט של גורמי הצורה (או המכשירים) שהשאילתה הנתונה כוללת:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
במקרה הזה, 3.77% מטעינות הדפים נמדדו במחשב, 2.88% בטאבלט ו-93.35% בטלפון, כלומר 100% בסה"כ.
סוגים של ערכי מדדים
שם המדד של CrUX API | סוג הנתונים | יחידות מדדים | צבירת נתונים סטטיסטיים | מאמרי עזרה |
---|---|---|---|---|
cumulative_layout_shift |
נקודה עשרונית עם קידוד כפול כמחרוזת | ללא יחידה | היסטוגרמה עם שלושה סלים, אחוזונים עם p75 | cls |
first_contentful_paint |
int | אלפיות שנייה | היסטוגרמה עם שלושה סלים, אחוזונים עם p75 | fcp |
first_input_delay (הוצאה משימוש) |
int | אלפיות שנייה | היסטוגרמה עם שלושה סלים, אחוזונים עם p75 | פיד |
interaction_to_next_paint |
int | אלפיות שנייה | היסטוגרמה עם שלושה סלים, אחוזונים עם p75 | inp |
largest_contentful_paint |
int | אלפיות שנייה | היסטוגרמה עם שלושה סלים, אחוזונים עם p75 | lcp |
experimental_time_to_first_byte |
int | אלפיות שנייה | היסטוגרמה עם שלושה סלים, אחוזונים עם p75 | ttfb |
form_factors |
דאבל ב-4 ספרות אחרי הנקודה העשרונית | אחוז | מיפוי מגורם צורה לשבר | גורמי צורה |
navigation_types |
דאבל ב-4 ספרות אחרי הנקודה העשרונית | אחוז | מיפוי מסוג הניווט לשבר | סוגי ניווט |
round_trip_time |
int | אלפיות שנייה | אחוזונים עם p75 | rtt |
מיפוי שמות של מדדים ב-BigQuery
שם המדד של CrUX API | שם המדד ב-BigQuery |
---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
first_input_delay |
first_input.delay |
interaction_to_next_paint |
interaction_to_next_paint |
largest_contentful_paint |
largest_contentful_paint |
experimental_time_to_first_byte |
experimental.time_to_first_byte |
navigation_types |
navigation_types |
form_factors |
לא רלוונטי |
round_trip_time |
לא רלוונטי |
תקופת האיסוף
החל מאוקטובר 2022, ב-CrUX API יש אובייקט collectionPeriod
עם השדות firstDate
ו-endDate
שמייצגים את תאריכי ההתחלה והסיום של חלון הצבירה. לדוגמה:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
כך תוכלו להבין טוב יותר את הנתונים ולבדוק אם הם עדיין עודכנו באותו יום, או אם הם מוחזרים כמו אתמול.
לידיעתכם, ה-CrUX API מאחר בערך יומיים אחרי התאריך של היום מכיוון שהוא ממתין לנתונים מלאים לאותו היום, ונדרש זמן עיבוד מסוים עד שהוא יהיה זמין ב-API. אזור הזמן שבו נעשה שימוש הוא שעון החוף המערבי (PST), ללא שינויים בשעון קיץ.
שאילתות לדוגמה
השאילתות נשלחות כאובייקטים של JSON באמצעות בקשת POST ל-https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
עם נתוני שאילתה כאובייקט JSON בגוף ה-POST:
{
"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:queryRecord?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
, הערכים יצטברו בכל גורמי הצורה.
למידע נוסף על שאילתות לדוגמה, אפשר לעיין במאמר שימוש ב-Chrome UX Report API.
צינור נתונים
מערך הנתונים של CrUX מעובד באמצעות צינור עיבוד נתונים כדי לאחד, לצבור ולסנן את הנתונים לפני שהם הופכים לזמינים באמצעות ה-API.
הממוצע הנע
הנתונים בדוח חוויית המשתמש ב-Chrome הם ממוצע נע של 28 ימים של מדדים מצטברים. כלומר, הנתונים שמוצגים בדוח חוויית המשתמש ב-Chrome בכל רגע נתון הם נתונים נצברים מ-28 הימים האחרונים.
הדבר דומה לאופן שבו מערך הנתונים של CrUX ב-BigQuery צובר דוחות חודשיים.
עדכונים יומיים
הנתונים מתעדכנים מדי יום בסביבות השעה 04:00 (שעון UTC). אין הסכם רמת שירות (SLA) לגבי זמני עדכון. היא מופעלת מדי יום בצורה הטובה ביותר.
סכימה
ב-CrUX API יש נקודת קצה אחת בלבד שמקבלת POST
בקשות HTTP. ה-API מחזיר ערך של record
שמכיל לפחות metrics
אחד שתואם לנתוני הביצועים של המקור או הדף המבוקשים.
בקשת HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.
גוף הבקשה
גוף הבקשה צריך להכיל נתונים עם המבנה הבא:
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
"metrics": [
string
],
// 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.
}
שדות | |
---|---|
effectiveConnectionType |
סוג החיבור האפקטיבי הוא מאפיין שאילתה שמציין את סוג הרשת בפועל שאליו צריכים להשתייך נתוני הרשומה. השדה הזה משתמש בערכים הערה: אם לא יצוין סוג חיבור יעיל, תוחזר רשומה מיוחדת עם נתונים נצברים מכל סוגי החיבורים שבאפקטיביים. |
formFactor |
גורם הצורה הוא מאפיין שאילתה שמציין את סוג המכשיר שאליו צריכים להשתייך נתוני הרשומה. שדה זה משתמש בערכים הערה: אם לא תציינו גורם צורה, תוחזר רשומה מיוחדת עם נתונים נצברים בכל גורמי הצורה. |
metrics[] |
המדדים שצריך לכלול בתשובה. אם לא תציינו מדדים, יוחזרו כל המדדים שנמצאו. הערכים המותרים: |
שדה איחוד url_ . url_pattern הוא המזהה הראשי לחיפוש רשומה. היא יכולה להיות רק אחת מהאפשרויות הבאות: |
|
origin |
ה'מקור' דוגמאות: |
url |
הערך דוגמאות: |
לדוגמה, כדי לבקש את ערכי התוכן הגדולים ביותר של תוכן מבוסס-תוכן למחשב בדף הבית של מסמכי התיעוד למפתחים של Chrome:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
גוף התשובה
בקשות שבוצעו בהצלחה מחזירות תשובות עם אובייקט record
ו-urlNormalizationDetails
במבנה הבא:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
לדוגמה, התגובה לגוף הבקשה בבקשה הקודמת יכולה להיות:
{
"record": {
"key": {
"formFactor": "DESKTOP",
"url": "https://developer.chrome.com/docs/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.9815
},
{
"start": 2500,
"end": 4000,
"density": 0.0108
},
{
"start": 4000,
"density": 0.0077
}
],
"percentiles": {
"p75": 651
}
}
},
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
}
}
מפתח
Key
מגדיר את כל המאפיינים שמזהים את הרשומה הזו כייחודיים.
{
"effectiveConnectionType": string,
"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 |
גורם הצורה הוא סוג המכשיר שבו השתמשו כל המשתמשים כדי לגשת לאתר עבור הרשומה הזו. אם גורם הצורה לא צוין, יוחזרו נתונים נצברים מכל גורמי הצורה. |
effectiveConnectionType |
סוג החיבור האפקטיבי הוא סוג החיבור הכללי שכל המשתמשים חוו ברשומה הזו. השדה הזה משתמש בערכים ["אופליין", "slow-2G", "2G", "3G", "4G"] כפי שמצוין בכתובת: https://wicg.github.io/netinfo/#effective-connection-types אם לא צוין סוג החיבור בפועל, יוחזרו נתונים נצברים מכל סוגי החיבורים בפועל. |
שדה איחוד url_ . תבנית ה-URL היא כתובת ה-URL שהרשומה חלה עליה. url_ יכול להיות רק אחת מהאפשרויות הבאות: |
|
origin |
הערה: כשמציינים |
url |
הערה: כשמציינים ערך מסוג |
מדדים
metric
הוא אוסף של נתונים נצברים של חוויית המשתמש לגבי מדד יחיד של ביצועים באינטרנט, כמו הצגת תוכן ראשוני (First-Party).
הוא עשוי להכיל היסטוגרמה מסכמת של השימוש ב-Chrome בעולם האמיתי כסדרה של bins
, נתוני אחוזון ספציפי
(למשל p75), או שהוא עשוי לכלול שברים מתויגים.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
או
{
"fractions": {
object (Fractions)
}
}
שדות | |
---|---|
histogram[] |
ההיסטוגרמה של חוויות המשתמש של מדד. ההיסטוגרמה תכלול לפחות סל אחד, והצפיפות של כל תאי האשפה תסתכם ב-1 בערך. |
percentiles |
אחוזונים שימושיים נפוצים של המדד. סוג הערך של האחוזונים יהיה זהה לסוגי הערכים שניתנו עבור פחי ההיסטוגרמה. |
fractions |
האובייקט הזה מכיל שברים מתויגים, שמסתכמים בערך 1. השברים יעוגלו ל-4 ספרות אחרי הנקודה העשרונית. |
סל
bin
הוא חלק נפרד של נתונים שנמשכים מההתחלה ועד הסוף, או אם לא מוגדר סוף מתחילתו ועד אינסוף חיובי.
ערכי ההתחלה והסיום של כל סל נכללים בסוג הערך של המדד שהוא מייצג. לדוגמה, הצגת תוכן ראשוני (First-Party) נמדדת באלפיות שנייה ונחשף כ-int, ולכן סלי המדדים של ה-int32 יתייחסו לסוגי ההתחלה והסיום. עם זאת, שינוי פריסה מצטבר נמדד בשברים עשרוניים ללא יחידה ונחשף כמחרוזת עשרונית, ולכן סלי המדדים שלו ישתמשו במחרוזות עבור סוג הערך.
{
"start": value,
"end": value,
"density": number
}
שדות | |
---|---|
start |
Start הוא ההתחלה של סל הנתונים. |
end |
End הוא הסוף של סל הנתונים. אם סוף לא מאוכלס, לסל אין סוף והוא תקין מההתחלה עד +inf. |
density |
שיעור המשתמשים שחוו את הערך של סל המודעות הזה עבור המדד הנתון. הצפיפות תעוגל ל-4 ספרות אחרי הנקודה העשרונית. |
אחוזונים
Percentiles
מכיל ערכים סינתטיים של מדד באחוזון סטטיסטי נתון. המדדים האלה משמשים להערכת הערך של מדד מסוים לפי אחוז המשתמשים מתוך מספר המשתמשים הכולל.
{
"P75": value
}
שדות | |
---|---|
p75 |
ב-75% מטעינות הדפים נמצא המדד הנתון בערך הזה או קטן ממנו. |
שברים
Fractions
מכיל שברים מתויגים שמצטברים עד 1~. כל תווית מתארת
של טעינת דף באופן מסוים, לכן אפשר להתייחס למדדים שמיוצגים באופן הזה בתור
מפיקה ערכים ייחודיים במקום ערכים מספריים, והשברים מבטאים
באיזו תדירות נמדד ערך ייחודי מסוים.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
בדומה לערכי הדחיסות בתאי ההיסטוגרמה, כל fraction
הוא מספר
0.0 <= value <= 1.0
, והם מסתכמים בערך 1.0.
UrlNormalization
אובייקט שמייצג את פעולות הנירמול שבוצעו כדי לנרמל כתובת URL ולהשיג סיכוי גבוה יותר לחיפוש מוצלח. מדובר בשינויים אוטומטיים פשוטים, אם מחפשים את ה-url_pattern
שסופקו כי אם הם ייכשלו. לא מטפלים בפעולות מורכבות כמו הפניות אוטומטיות שמתרחשות בהמשך.
{
"originalUrl": string,
"normalizedUrl": string
}
שדות | |
---|---|
originalUrl |
כתובת ה-URL המקורית המבוקשת לפני פעולות נירמול. |
normalizedUrl |
כתובת ה-URL אחרי פעולות נירמול. זוהי כתובת URL חוקית של חוויית משתמש שניתן לחפש אותה באופן סביר. |
מגבלות קצב של יצירת בקשות
ממשק CrUX API מוגבל ל-150 שאילתות לדקה בלבד לכל פרויקט ב-Google Cloud, שמוצע ללא תשלום. אפשר לראות את המגבלה הזו ואת השימוש הנוכחי שלכם במסוף Google Cloud. המכסה הנדיבה הזו אמורה להספיק לרוב המכריע של תרחישי השימוש, ואי אפשר לשלם על מכסה מוגדלת.