באמצעות CrUX API אפשר לגשת עם זמן אחזור קצר לנתונים נצברים של חוויית משתמש אמיתית ברמת הפירוט של הדף והמקור.
תרחיש נפוץ
ה-CrUX API מאפשר לשלוח שאילתות לגבי מדדי חוויית משתמש עבור URI ספציפי, כמו 'קבלת מדדים עבור המקור https://example.com
'.
מפתח API של CrUX
כדי להשתמש ב-CrUX API נדרש מפתח Google Cloud 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
מציין שהרשומה מכילה מידע על טעינות שבוצעו במכשיר נייד. לכל מאפיין יהיה מספר מסוים של ערכים. אם לא מציינים את המאפיין, המאפיין הזה יצבור נתונים מכל הערכים. לדוגמה, ציון 'ללא גורם צורה' מציין שרשומה מכילה מידע על טעינות שבוצעו בגורם צורה כלשהו.
מבנה
מחלקת המכשיר שבה משתמש הקצה השתמש כדי לנווט לדף. זוהי קבוצה כללית של מכשירים שמפוצלת ל-PHONE
, ל-TABLET
ול-DESKTOP
.
סוג החיבור בפועל
סוג החיבור האפקטיבי הוא איכות החיבור המשוערת של המכשיר בזמן הניווט לדף. זוהי כיתה כללית שפוצלה ל-offline
, slow-2G
, 2G
, 3G
ו-4G
.
המדד
אנו מדווחים על מדדים כצבירות סטטיסטיות, בהיסטוגרמות, באחוזונים ושברים.
ערכים של נקודות צפות מעוגלים ל-4 ספרות אחרי הנקודה העשרונית (יש לשים לב שהמדדים cumulative_layout_shift
מקודדים פעמיים כמחרוזת, ולכן הם לא מחושבים כערכי נקודה צפה, והדיווח עליהם כולל 2 ספרות אחרי הנקודה העשרונית).
היסטוגרמה
כאשר המדדים מבוטאים בהיסטוגרמה, אנחנו מציגים את אחוזי טעינות הדף בטווחים מסוימים של אותו מדד.
היסטוגרמה פשוטה של שלוש בנות עבור מדד לדוגמה נראית כך:
{
"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 |
מקום עם 2 ספרות אחרי הנקודה העשרונית, מקודד פעמיים כמחרוזת | חסר יחידה | היסטוגרמה עם שלושה פחים, אחוזונים עם 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 ספרות אחרי הנקודה העשרונית | percent | מיפוי מגורם צורה לשבר | גורמי צורה |
navigation_types |
דאבל עם 4 ספרות אחרי הנקודה העשרונית | percent | מיפוי מסוג ניווט לשבר | סוגי ניווט |
מיפוי שמות של מדד ב-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 |
לא רלוונטי |
תקופת האיסוף
החל מאוקטובר 2022, ממשק ה-API של CrUX כולל אובייקט collectionPeriod
עם השדות firstDate
ו-endDate
שמייצגים את תאריכי ההתחלה והסיום של חלון הצבירה. למשל:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
כך אפשר להבין טוב יותר את הנתונים ואם הם עדיין עודכנו באותו יום או אם הם מחזירים את אותם נתונים כמו אתמול.
שימו לב שממשק ה-API של CrUX חל עיכוב של כיומיים מהתאריך של היום, מאחר שהוא ממתין לנתונים מלאים במשך היום, ונדרש זמן עיבוד מסוים לפני שהוא זמין ב-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 יש נקודת קצה אחת (endpoint) אחת שמקבלת בקשות HTTP מסוג POST
. ה-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 |
הערך 'origin' של דוגמאות: |
url |
השדה דוגמאות: |
לדוגמה, כדי לבקש את ערכי ה-LCP הגדולים ביותר במחשב עבור דף הבית של מסמכי התיעוד למפתחים ב-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 |
סוג החיבור בפועל הוא סיווג החיבור הכללי שכל המשתמשים חווים ברשומה הזו. בשדה הזה נעשה שימוש בערכים ["offline", "slow-2G", "2G", "3G", "4G"] כפי שצוין ב-https://wicg.github.io/netinfo/#effective-connection-types אם לא צוין סוג החיבור בפועל, יוחזרו נתונים נצברים של כל סוגי החיבורים בפועל. |
שדה איחוד url_ . תבנית ה-URL היא כתובת ה-URL שעליה הרשומה חלה. url_ יכול להיות רק אחד מהבאים: |
|
origin |
הערה: כשמציינים |
url |
הערה: כשמציינים |
מדדים
metric
הוא קבוצה של נתונים נצברים של חוויית המשתמש למדד ביצועים יחיד באינטרנט, כמו הצגת תוכן ראשוני (FCP).
היא עשויה להכיל היסטוגרמה מסכמת של השימוש ב-Chrome בעולם האמיתי כסדרה של bins
, נתוני אחוזונים ספציפיים (כמו p75), או שהיא עשויה להכיל שברים מתויגים.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
או
{
"fractions": {
object (Fractions)
}
}
שדות | |
---|---|
histogram[] |
ההיסטוגרמה של חוויות המשתמש למדד. ההיסטוגרמה תכלול לפחות סל אחד והצפיפות של כל הסלים תסתכם בכ-1. |
percentiles |
אחוזים שימושיים נפוצים של המדד. סוג הערך של האחוזים יהיה זהה לסוגי הערכים שניתנו עבור סלי ההיסטוגרמה. |
fractions |
האובייקט מכיל שברים מתויגים, שסוכמו עד כ-1. שברים מעוגלים ל-4 ספרות אחרי הנקודה העשרונית. |
סל
bin
הוא חלק נפרד מנתונים שנצברו מתחילתו ועד סופו, או אם לא ניתן לו סיום מתחילתו ועד סופו החיובי.
ערכי ההתחלה והסיום של סל מצוינים בסוג הערך של המדד שהוא מייצג. לדוגמה, המהירות שבה נטען רכיב התוכן הראשון נמדדת באלפיות השנייה ונחשפת כ-ints, ולכן הסלים המטריים שלו ישתמשו ב-int32 בסוגי ההתחלה והסיום. עם זאת, שינוי פריסה מצטבר נמדד בשברים עשרוניים ללא יחידה והוא חשוף כמחרוזת עשרונית המקודדת כמחרוזת, ולכן סלי המדדים שלו ישתמשו במחרוזות עבור סוג הערך שלו.
{
"start": value,
"end": value,
"density": number
}
שדות | |
---|---|
start |
Start היא תחילת סל הנתונים. |
end |
End הוא הסוף של סל הנתונים. אם הפרמטר 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 תוכלו לראות את המגבלה הזו ואת השימוש הנוכחי שלכם. המכסה הנדיבה הזו אמורה להספיק לרוב המכריע של תרחישי השימוש, ואי אפשר לשלם על מכסה מוגדלת.