איך משתמשים ב-CrUX API

כאן מוסבר איך להשתמש ב-Chrome UX Report API כדי לקבל גישה לנתוני חוויית משתמש אמיתיים במיליוני אתרים.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

מערך הנתונים של הדוח על חוויית המשתמש ב-Chrome (CrUX) מייצג את החוויה של משתמשי Chrome אמיתיים ביעדים פופולריים באינטרנט. מאז 2017, כשהשקנו לראשונה את מערך הנתונים שאפשר להריץ עליו שאילתות ב-BigQuery, שילבנו נתוני שטח מ-CrUX בכלי פיתוח כמו PageSpeed Insights והדוח הבסיסי על ביצועי הדף באינטרנט ב-Search Console. כך מפתחים יכולים למדוד ולעקוב אחרי חוויות משתמש אמיתיות. הכלי שחסר עד עכשיו הוא כלי שמספק גישה חופשית לנתוני CrUX באמצעות RESTful באופן פרוגרמטי. כדי לצמצם את הפער הזה, אנחנו שמחים להודיע על השקת Chrome UX Report API החדש.

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

כדי להבטיח למפתחים גישה לכל המדדים החשובים ביותר – מדדי הליבה לבדיקת חוויית המשתמש באתר – ה-CrUX API מבצע ביקורת ומעקב אחרי המדד Largest Contentful Paint‏ (LCP), המדד Interaction to Next Paint‏ (INP) והמדד Cumulative Layout Shift‏ (CLS) ברמת המקור וברמת כתובת ה-URL.

אז בואו נראה איך משתמשים בו.

התנסות עם ה-API בדף הזה

כדאי לנסות!

שאילתות על נתוני מקור

מקורות במערך הנתונים של CrUX כוללים את כל חוויות המשתמשים ברמת הדף. בדוגמה הבאה מוצג איך להריץ שאילתה ב-CrUX API כדי לקבל נתוני חוויית משתמש של מקור באמצעות curl בשורת הפקודה.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data ';{"origin": "https://web.dev"}'

הפקודה curl מורכבת משלושה חלקים:

  1. נקודת הקצה של ה-API בכתובת URL, כולל מפתח ה-API הפרטי של המתקשר.
  2. הכותרת Content-Type: application/json, שמציינת שגוף הבקשה מכיל JSON.
  3. גוף הבקשה בקידוד JSON, שבו מצוין המקור https://web.dev.

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

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.s>tringify(requestBody)
  }).then(r>esponse = response.json()).then(response = {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

מחליפים את [YOUR_API_KEY] במפתח שלכם. לאחר מכן, קוראים לפונקציה CrUXApiUtil.query ומעבירים את אובייקט request body.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(re>sponse = {
  console.log(response);
}).catch(re>sponse = {
  console.error(response);
});

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

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            ";density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

המאפיינים start ו-end של האובייקט histogram מייצגים את טווח הערכים שמשתמשים חווים עבור המדד הנתון. המאפיין density מייצג את שיעור חוויות המשתמש בטווח הזה. בדוגמה הזו, 79% מחוויית המשתמש של LCP בכל דפי web.dev הם מתחת ל-2,500 מילישניות, שהוא ערך הסף של LCP שמוגדר כטוב. הערך percentiles.p75 מציין ש-75% מחוויית המשתמשים בהתפלגות הזו נמוכה מ-2,216 מילישניות. מידע נוסף על מבנה התשובה מופיע במסמכי התיעוד בנושא גוף התשובה.

שגיאות

אם אין ל-CrUX API נתונים לגבי מקור מסוים, הוא מגיב בהודעת שגיאה בפורמט JSON:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

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

שגיאה
{"origin": "http://www.web.dev"}

המקור הזה כולל באופן שגוי את הפרוטוקול http:// ואת תת-הדומיין www..

הפעולה הצליחה
{"origin": "https://web.dev"}

המקור הזה נגיש לכולם.

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

שאילתת נתוני כתובות URL

ראיתם איך לשלוח שאילתה ל-CrUX API כדי לקבל את חוויית המשתמש הכוללת במקור. כדי להגביל את התוצאות לדף מסוים, משתמשים בפרמטר הבקשה url.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

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

כדי לשלוח שאילתה לנתוני כתובות URL מ-CrUX API ב-JavaScript, קוראים לפונקציה CrUXApiUtil.query באמצעות הפרמטר url בגוף הבקשה.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(re>sponse = {
  console.log(response);
}).catch(re>sponse = {
  console.error(response);
});

אם יש נתונים לכתובת ה-URL הזו במערך הנתונים של CrUX, ה-API יחזיר תגובה בקידוד JSON. לדוגמה

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

התוצאות מראות ש-https://web.dev/fast/ כולל 85% חוויות LCP 'טובות' ומאון 75 של 1,947 מילי-שניות, שזה קצת יותר טוב מההתפלגות ברמת המקור.

נירמול כתובות URL

יכול להיות ש-CrUX API יבצע נורמליזציה של כתובות URL שהתבקשו כדי להתאים אותן טוב יותר לרשימת כתובות ה-URL המוכרות. לדוגמה, שאילתה לגבי כתובת ה-URL https://web.dev/fast/#measure-performance-in-the-field תניב נתונים לגבי https://web.dev/fast/ בגלל הנורמליזציה. במקרה כזה, אובייקט urlNormalizationDetails ייכלל בתשובה.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

במאמרים בנושא CrUX יש מידע נוסף על נירמול כתובות URL.

שאילתה לפי גורם צורה

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

ה-API תומך בשלושה ערכים מפורשים של גורם צורה: DESKTOP,‏ PHONE ו-TABLET. בנוסף למקור או לכתובת ה-URL, צריך לציין אחד מהערכים האלה בגוף הבקשה כדי להגביל את התוצאות רק לחוויית המשתמש הזו. בדוגמה הזו מוסבר איך לשלוח שאילתה ל-API לפי גורם צורה באמצעות curl.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

כדי לשלוח שאילתה ל-CrUX API לגבי נתונים ספציפיים לגורם צורה באמצעות JavaScript, קוראים לפונקציה CrUXApiUtil.query באמצעות הפרמטרים url ו-formFactor בגוף הבקשה.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
})>.then(response = {
  console.log(response);
}).>catch(response = {
  console.error(response);
});

השמטה של הפרמטר formFactor שקולה לבקשת נתונים עבור כל גורמי הצורה יחד.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

השדה key בתגובה יחזיר את הגדרות הבקשה formFactor כדי לאשר שכלולות רק חוויות שימוש בטלפון.

בסעיף הקודם ראינו ש-85% מחוויית המשתמש בדף הזה קיבלו ציון LCP טוב. לעומת זאת, רק 78% מהחוויות שמותאמות לטלפון נחשבות ל'טובות'. גם האחוזון ה-75 איטי יותר בחוויות שימוש בטלפון, ועלה מ-1,947 אלפיות השנייה ל-2,366 אלפיות השנייה. פילוח לפי גורם צורה יכול להדגיש פערים קיצוניים יותר בחוויית המשתמש.

הערכת הביצועים של מדדי הליבה לבדיקת חוויית המשתמש באתר

במסגרת התוכנית Core Web Vitals מוגדרים יעדים שעוזרים לקבוע אם חוויית המשתמש או חלוקת החוויות יכולות להיחשב כ'טובות'. בדוגמה הבאה, אנחנו משתמשים ב-CrUX API ובפונקציה CrUXApiUtil.query כדי להעריך אם הפיזור של מדדי ה-Core Web Vitals (LCP, ‏ INP, ‏ CLS) בדף אינטרנט הוא 'טוב'.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(re>sponse = {
  assessCoreWebVitals(response);
}).catch(re>sponse = {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  >CORE_WEB_VITALS.forEach(metric = {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the &<quot;good" threshold.
    const passes = p75  threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

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

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals ";good" threshold (0.10).

אפשר להשתמש בנתונים מ-CrUX בשילוב עם דרך אוטומטית למעקב אחרי תוצאות ה-API, כדי לוודא שחוויית המשתמשים האמיתיים מהירה ונשארת מהירה. מידע נוסף על מדדי הליבה לבדיקת חוויית המשתמש באתר ועל אופן המדידה שלהם זמין במאמרים Web Vitals וTools to measure Core Web Vitals.

מה השלב הבא?

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

  • מדדים נוספים
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • מאפיינים נוספים
    • month
    • country
  • רמת פירוט נוספת
    • היסטוגרמות מפורטות
    • עוד אחוזונים

כדי לקבל מפתח API ולעיין בדוגמאות נוספות של אפליקציות, אפשר לעיין במסמכי ה-API הרשמיים של CrUX. נשמח אם תנסו את התכונה החדשה, ונשמח לקבל שאלות או משוב בפורום הדיונים של CrUX. כדי להתעדכן בכל התוכניות שלנו לגבי CrUX API, אפשר להירשם לפורום ההודעות של CrUX או לעקוב אחרינו ב-Twitter בכתובת @ChromeUXReport.