ממשק API של CrUX

באמצעות 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	לא רלוונטי

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

תקופת האיסוף

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

הערה: הדוגמה הקודמת מתייחסת למערכות מבוססות 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 יש נקודת קצה אחת (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	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 הערך 'origin' של url_pattern מתייחס לדפוס כתובת 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 מגדיר את כל המאפיינים שמזהים את הרשומה הזו כייחודיים.

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

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

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

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