ממשק API של CrUX

ב-CrUX API יש גישה עם זמן אחזור קצר לנתונים נצברים של חוויית משתמש אמיתיים ברמת הפירוט של הדף והמקור.

תרחיש לדוגמה נפוץ

ה-CrUX API מאפשר לשלוח שאילתות על מדדי חוויית המשתמש עבור URI ספציפי, כמו "קבלת מדדים למקור https://example.com".

מפתח API של CrUX

כדי להשתמש ב-CrUX API נדרש מפתח API של Google Cloud. אפשר ליצור חשבון בדף פרטי כניסה ולהקצות אותו לשימוש של 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

כאשר המזהה הוא כתובת 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	לא רלוונטי

הערה: ב-CrUX BigQuery, צפיפות ההיסטוגרמה עולה עד 100% לכל מקור בגורמי צורה, כך שהמדד form_factors שבו אנחנו תומכים ב-API מתבטא במקום זאת כצפיפות ההיסטוגרמה של first_contentful_paint.

תקופת האיסוף

החל מאוקטובר 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"]}'

הערה: הדוגמה הקודמת מתייחסת למערכות macOS או Linux, כולל מעטפת Git BASH ל-Windows. במערכות אחרות יכול להיות שיהיה צורך לבצע שינויים קלים. לדוגמה, אי אפשר להשתמש במירכאות כפולות לפרמטרים וגם לא במירכאות כפולות (\) בשורת הפקודה cmd.exe. לכן, יש צורך להשתמש במירכאות כפולות (התווספת למירכאות פנימיות בהתאם למחרוזת \") וגם לא להשתמש בשורה יחידה.

נתונים ברמת הדף זמינים דרך ה-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) לגבי זמני העדכון. העדכון פועל על בסיס התוצאה הטובה ביותר מדי יום.

זהירות: הנתונים לא יהיו שונים באותו יום לאחר שהם יעודכנו בסביבות השעה 04:00 (שעון UTC), אבל שיחות חוזרות יניבו את אותן התוצאות.

סכימה

ב-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	string סוג החיבור האפקטיבי הוא מאפיין שאילתה שמציין את סוג הרשת בפועל שאליו צריכים להשתייך נתוני הרשומה. השדה הזה משתמש בערכים ["offline", "slow-2G", "2G", "3G", "4G"] כפי שמצוינים במפרט של Network Information API הערה: אם לא יצוין סוג חיבור יעיל, תוחזר רשומה מיוחדת עם נתונים נצברים מכל סוגי החיבורים שבאפקטיביים.
formFactor	enum (FormFactor) גורם הצורה הוא מאפיין שאילתה שמציין את סוג המכשיר שאליו צריכים להשתייך נתוני הרשומה. השדה הזה משתמש בערכים DESKTOP, PHONE או TABLET. הערה: אם לא תציינו גורם צורה, תוחזר רשומה מיוחדת עם נתונים נצברים בכל גורמי הצורה.
metrics[]	string המדדים שצריך לכלול בתשובה. אם לא תציינו מדדים, יוחזרו כל המדדים שנמצאו. הערכים המותרים: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
שדה איחוד url_pattern. url_pattern הוא המזהה הראשי לחיפוש רשומה. היא יכולה להיות רק אחת מהאפשרויות הבאות:
origin	string הערך url_pattern 'origin' מתייחס לתבנית URL שהיא המקור של האתר. דוגמאות: "https://example.com", "https://cloud.google.com"
url	string הערך url_pattern url מתייחס לתבנית URL שהיא כל כתובת URL שרירותית. דוגמאות: "https://example.com/, https://cloud.google.com/why-google-cloud/"

לדוגמה, כדי לבקש את ערכי התוכן הגדולים ביותר של תוכן מבוסס-תוכן למחשב בדף הבית של מסמכי התיעוד למפתחים של 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	enum (FormFactor) גורם הצורה הוא סוג המכשיר שבו השתמשו כל המשתמשים כדי לגשת לאתר עבור הרשומה הזו. אם גורם הצורה לא צוין, יוחזרו נתונים נצברים מכל גורמי הצורה.
effectiveConnectionType	string סוג החיבור האפקטיבי הוא סוג החיבור הכללי שכל המשתמשים חוו ברשומה הזו. השדה הזה משתמש בערכים ["אופליין", "slow-2G", "2G", "3G", "4G"] כפי שמצוין בכתובת: https://wicg.github.io/netinfo/#effective-connection-types אם לא צוין סוג החיבור בפועל, יוחזרו נתונים נצברים מכל סוגי החיבורים בפועל.
שדה איחוד url_pattern. תבנית ה-URL היא כתובת ה-URL שהרשומה חלה עליה. url_pattern יכול להיות רק אחת מהאפשרויות הבאות:
origin	string origin מציין את המקור שעבורו הרשומה הזו מיועדת. הערה: כשמציינים origin, הנתונים של טעינות במקור הזה לגבי כל הדפים נצברים לנתוני חוויית המשתמש ברמת המקור.
url	string url מציין כתובת URL ספציפית עבור הרשומה הזו. הערה: כשמציינים ערך מסוג url בלבד לגבי כתובת ה-URL הספציפית הזו, הנתונים נצברים.

מדדים

metric הוא אוסף של נתונים נצברים של חוויית המשתמש לגבי מדד יחיד של ביצועים באינטרנט, כמו הצגת תוכן ראשוני (First-Party). הוא עשוי להכיל היסטוגרמה מסכמת של השימוש ב-Chrome בעולם האמיתי כסדרה של bins, נתוני אחוזון ספציפי (כמו p75), או שהיא מכילה שברים מתויגים.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

או

{
  "fractions": {
    object (Fractions)
  }
}

שדות
histogram[]	object (Bin) ההיסטוגרמה של חוויות המשתמש של מדד. ההיסטוגרמה תכלול לפחות סל אחד, והצפיפות של כל תאי האשפה תסתכם ב-1 בערך.
percentiles	object (Percentiles) אחוזונים שימושיים נפוצים של המדד. סוג הערך של האחוזונים יהיה זהה לסוגי הערכים שניתנו עבור פחי ההיסטוגרמה.
fractions	object (Fractions) האובייקט הזה מכיל שברים מתויגים, שמסתכמים בערך 1. השברים יעוגלו ל-4 ספרות אחרי הנקודה העשרונית.

סל

bin הוא חלק נפרד של נתונים שנמשכים מההתחלה ועד הסוף, או אם לא מוגדר סוף מתחילתו ועד אינסוף חיובי.

ערכי ההתחלה והסיום של כל סל נכללים בסוג הערך של המדד שהוא מייצג. לדוגמה, הצגת תוכן ראשוני (First-Party) נמדדת באלפיות שנייה ונחשף כ-int, ולכן סלי המדדים של ה-int32 יתייחסו לסוגי ההתחלה והסיום. עם זאת, שינוי פריסה מצטבר נמדד בשברים עשרוניים ללא יחידה ונחשף כמחרוזת עשרונית, ולכן סלי המדדים שלו ישתמשו במחרוזות עבור סוג הערך.

{
  "start": value,
  "end": value,
  "density": number
}

שדות
start	(integer | string) Start הוא ההתחלה של סל הנתונים.
end	(integer | string) End הוא הסוף של סל הנתונים. אם סוף לא מאוכלס, לסל אין סוף והוא תקין מההתחלה עד +inf.
density	number שיעור המשתמשים שחוו את הערך של סל המודעות הזה עבור המדד הנתון. הצפיפות תעוגל ל-4 ספרות אחרי הנקודה העשרונית.

אחוזונים

Percentiles מכיל ערכים סינתטיים של מדד באחוזון סטטיסטי נתון. המדדים האלה משמשים להערכת הערך של מדד מסוים לפי אחוז המשתמשים מתוך מספר המשתמשים הכולל.

{
  "P75": value
}

שדות
p75	(integer | string) ב-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	string כתובת ה-URL המקורית המבוקשת לפני פעולות נירמול.
normalizedUrl	string כתובת ה-URL אחרי פעולות נירמול. זוהי כתובת URL חוקית של חוויית משתמש שניתן לחפש אותה באופן סביר.

מגבלות קצב של יצירת בקשות

ממשק CrUX API מוגבל ל-150 שאילתות לדקה בלבד לכל פרויקט ב-Google Cloud, שמוצע ללא תשלום. אפשר לראות את המגבלה הזו ואת השימוש הנוכחי שלכם במסוף Google Cloud. המכסה הנדיבה הזו אמורה להספיק לרוב המכריע של תרחישי השימוש, ואי אפשר לשלם על מכסה מוגדלת.