ממשק API של CrUX

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

כדאי לנסות!

תרחיש שימוש נפוץ

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

מפתח API של CrUX

כדי להשתמש ב-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,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%.

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

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

תקופת האיסוף

החל מאוקטובר 2022, ה-API של CrUX מכיל אובייקט 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_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) לגבי זמני העדכון. העדכון מתבצע על בסיס 'עושים את המקסימום' מדי יום.

סכימה

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

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

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