ממשק API של CrUX

ב-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	2 ספרות אחרי הנקודה העשרונית, עם קידוד כפול כמחרוזת	ללא יחידה	היסטוגרמה עם שלושה סלים, אחוזונים עם p75	cls
first_contentful_paint	int	אלפיות שנייה	היסטוגרמה עם שלושה סלים, אחוזונים עם p75	fcp
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
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
• 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). אין הסכם רמת שירות לגבי זמני העדכון. העדכונים מתבצעים מדי יום לפי היכולת.

זהירות: הנתונים לא יהיו שונים באותו יום לאחר שהם יעודכנו בסביבות השעה 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", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
שדה איחוד url_pattern. url_pattern הוא המזהה הראשי לחיפוש רשומה. הוא יכול להיות רק אחד מהאפשרויות הבאות:
origin	string ה'מקור' url_pattern מתייחס לתבנית כתובת אתר שהיא המקור של אתר. דוגמאות: "https://example.com", "https://cloud.google.com"
url	string הערך url_pattern url מתייחס לתבנית URL שהיא כל כתובת URL שרירותית. דוגמאות: "https://example.com/,‏ https://cloud.google.com/why-google-cloud/"

לדוגמה, כדי לבקש את הערכים של המהירות שבה נטען במחשב רכיב התוכן הכי גדול (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	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. המכסה הנדיבה הזו אמורה להספיק לרוב המכריע של תרחישי השימוש, ואי אפשר לשלם על מכסה מוגדלת.