ממשק API של CrUX

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

כדאי לנסות!

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

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

מפתח CrUX API

כדי להשתמש ב-CrUX API, צריך מפתח Google Cloud API שמוקצה לשימוש ב-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.

מדד

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

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

סוגי ערכי המדדים

מיפוי שמות של מדדים ב-BigQuery

תקופת האיסוף

החל מאוקטובר 2022, CrUX API מכיל אובייקט collectionPeriod עם השדות firstDate ו-endDate שמייצגים את תאריכי ההתחלה והסיום של חלון הצבירה. לדוגמה:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

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

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

בנוסף, בcollectionPeriod תמיד יוצגו 28 ימים, גם אם הנתונים לא מתייחסים ל-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"]}'

כדי לקבל נתונים ברמת הדף דרך ה-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_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• ‫form_factors (מדווח רק אם לא צוין formFactor בבקשה)
• experimental_ad_count (מדווח רק לגבי דפים שנכללים במדדי המודעות)
• experimental_ad_density (מדווח רק לגבי דפים שנכללים במדדי המודעות)
• experimental_ad_cpu (מדווח רק לגבי דפים שנכללים במדדי המודעות)
• experimental_ad_kilobytes (מדווח רק לגבי דפים שנכללים במדדי המודעות)

אם לא מציינים ערך ל-formFactor, הערכים יצטברו בכל הפלטפורמות.

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

פייפליין

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

הממוצע הנע

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

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

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

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

סכימה

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

בקשת HTTP

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

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

גוף הבקשה

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

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

לדוגמה, כדי לבקש את ערכי ה-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.
}

מדדים

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

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

או

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

סל האשפה

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

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

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

אחוזונים

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

{
  "P75": value
}

שברים

‫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
}

מגבלות קצב

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