ממשק 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%.

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

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

תקופת האיסוף

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

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

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

חשוב לזכור שנתוני ה-API של CrUX מתייחסים לתאריך של לפני יומיים בערך, כי המערכת ממתינה לנתונים מלאים של היום, ויש זמן עיבוד מסוים עד שהם יהיו זמינים ב-API. אזור הזמן שבו נעשה שימוש הוא שעון החוף המערבי בארה"ב (PST) ללא שינויים בשעון הקיץ.

בנוסף, תמיד יוצגו 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"]}'

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

סכימה

יש נקודת קצה אחת ל-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.
}

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

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

או

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

סל

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

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

הגבלות קצב

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