ממשק API של CrUX

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

רוצים לנסות?

תרחיש לדוגמה

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

מפתח API של CrUX

כדי להשתמש ב-CrUX API נדרש מפתח API של Google Cloud שהוקצה לשימוש ב-Chrome UX Report API.

קבלה של מפתח API ושימוש בו

קבלת מפתח

לחלופין, אפשר ליצור אחד בדף Credentials.

אחרי שתקבלו מפתח 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.

מדד

אנחנו מדווחים על מדדים כצבירות סטטיסטיות, בהיסטוגרמות, במאונים ובשברונים.

ערכי נקודה צפה (float) מעוגלים ל-4 ספרות אחרי הנקודה העשרונית (שימו לב שהמדדים cumulative_layout_shift הם מספרים כפולים (double) שמקודדים כמחרוזת, ולכן הם לא נחשבים לערכים של נקודה צפה (float) ומדווחים ל-2 ספרות אחרי הנקודה העשרונית במחרוזת).

היסטוגרמה

כשהמדדים מוצגים בהיסטוגרמה, אנחנו מציגים את האחוזים של טעינות הדפים שנכללות בטווחים מסוימים של המדד הזה.

היסטוגרמה של שלוש קטגוריות לדוגמה של מדד נראה כך:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

הנתונים האלה מצביעים על כך שב-38.18% מהטעינות של הדפים, המדד לדוגמה נמדד בין 0ms ל-1,000ms. היחידות של המדד לא נכללות בתרשים ההיסטוגרמה הזה, במקרה הזה נניח שמדובר במילישניות.

בנוסף, ב-49.91% מהטעינות של הדפים, ערך המדד היה בין 1,000ms ל-3,000ms, וב-11.92% מהטעינות ערך המדד היה גבוה מ-3,000ms.

מאונים

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

{
  "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) ללא שינויים בשעון הקיץ.

תקופת האיסוף זמינה גם ב-PageSpeed Insights:

תאריכי תקופת האיסוף ב-PageSpeed Insights.

בנוסף, תמיד יוצגו 28 ימים ב-collectionPeriod, גם אם הנתונים לא מתייחסים ל-28 הימים המלאים (לדוגמה, אם דף הושק לפני פחות מ-28 ימים). השדה collectionPeriod מייצג את פרק הזמן שבו נתוני CrUX נצברו, ולא בהכרח את פרק הזמן שהנתונים מייצגים.

שאילתות לדוגמה

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

שאילתות לדוגמה נוספות מפורטות במאמר שימוש ב-API של דוח חוויית המשתמש של Chrome.

צינור עיבוד נתונים

מערך הנתונים של CrUX עובר עיבוד באמצעות צינור עיבוד נתונים כדי לאחד, לצבור ולסנן את הנתונים לפני שהם יהיו זמינים באמצעות ה-API.

הממוצע הנע

הנתונים בדוח חוויית המשתמש של Chrome הם ממוצע נע של 28 ימים של מדדים מצטברים. כלומר, הנתונים שמוצגים בדוח חוויית המשתמש ב-Chrome בכל זמן נתון הם למעשה נתונים מ-28 הימים האחרונים שנצברו יחד.

האופן שבו הנתונים נצברים דומה לאופן שבו מערך הנתונים של CrUX ב-BigQuery אוסף דוחות חודשיים.

עדכונים יומיים

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

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

סכימה

יש נקודת קצה אחת ל-CrUX API שמקבלת בקשות HTTP מסוג POST. ה-API מחזיר record שמכיל metrics אחד או יותר שתואם לנתוני הביצועים של המקור או הדף המבוקשים.

בקשת HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.

גוף הבקשה

גוף הבקשה צריך להכיל נתונים במבנה הבא:

{
  "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.
}

שדות
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 '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/"

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

{
  "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) גורם הצורה הוא סוג המכשיר שבו כל המשתמשים השתמשו כדי לגשת לאתר עבור הרשומה הזו. אם לא מציינים את גורם הצורה, המערכת תחזיר נתונים מצטברים של כל גורמי הצורה.
שדה האיחוד url_pattern. תבנית ה-URL היא כתובת ה-URL שהרשומה חלה עליה. הערך של url_pattern יכול להיות רק אחת מהאפשרויות הבאות:
origin	string השדה origin מציין את המקור של הרשומה הזו. הערה: כשמציינים origin, הנתונים של טעינות במקור הזה בכל הדפים נצברים בנתוני חוויית המשתמש ברמת המקור.
url	string השדה url מציין כתובת URL ספציפית שהרשומה הזו מיועדת לה. הערה: כשמציינים url, המערכת תצבור רק נתונים לגבי כתובת ה-URL הספציפית הזו.

מדדים

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

ערכי ההתחלה והסיום של קטגוריה נתונים לפי סוג הערך של המדד שהיא מייצגת. לדוגמה, הזמן של ציור התוכן הראשון נמדד במילישניות ומוצג כמספרים שלמים, ולכן בקטגוריות המדדים שלו נעשה שימוש ב-int32 לסוגים 'התחלה' ו'סיום'. עם זאת, שינוי המיקום המצטבר של הפריסה נמדד בעשרוניים ללא יחידה ומוצג כעשרוני שמקודד כמחרוזת, ולכן בקטגוריות המדדים שלו נעשה שימוש במחרוזות כסוג הערך.

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

שדות
start	(integer | string) Start הוא תחילת אשכול הנתונים.
end	(integer | string) End הוא סוף קטגוריית הנתונים. אם הערך של end לא מאוכלס, לקטגוריה אין סוף והיא תקפה מ-start עד +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. המכסה הנדיבה הזו אמורה להספיק לרוב המכריע של תרחישים לדוגמה, ואי אפשר לשלם על הגדלת המכסה.