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

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

Rick Viscomi

Shane Exterkamp

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

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

כדי שלמפתחים תהיה גישה לכל המדדים החשובים ביותר – מדדי הליבה לבדיקת חוויית המשתמש באתר – ממשק CrUX API מבצע ביקורת וניטור של המהירות שבה נטען רכיב התוכן הכי גדול (LCP) (LCP), עיכוב בקלט ראשון (FID) וCumulative Layout Shift (CLS) גם ברמת המקור וגם ברמת כתובת ה-URL.

אז בוא נצלול פנימה ונראה איך להשתמש בה!

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

המקורות במערך הנתונים של 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"}'

הערה: כל בקשות ה-API חייבות לספק ערך לפרמטר key – הערך [YOUR_API_KEY] בדוגמה הקודמת נשאר כ-placeholder. ניתן לקבל מפתח API פרטי משלך ל-CrUX, כפי שמתואר במסמכי התיעוד של CrUX API.

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

1. נקודת הקצה של כתובת ה-URL של ה-API, כולל מפתח ה-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.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

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

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

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

{
  "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(response => {
  console.log(response);
}).catch(response => {
  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

ה-API של CrUX עשוי לנרמל את כתובות ה-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"
  }
}

מידע נוסף על נירמול כתובות URL זמין במסמכי התיעוד של CrUX.

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

מונח מפתח: גורם צורה הוא סוג המכשיר שבו המשתמש נכנס לאתר. סוגי המכשירים הנפוצים הם מחשבים, טלפון וטאבלטים.

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

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

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

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

בתוכנית מדדי הליבה לבדיקת חוויית המשתמש באתר מוגדרים יעדים שעוזרים לקבוע אם חוויית משתמש או התפלגות חוויות יכולות להיחשב 'טובה'. בדוגמה הבאה, אנחנו משתמשים ב-CrUX API ובפונקציה CrUXApiUtil.query כדי לבדוק אם ההתפלגות של מדדי הליבה לבדיקת חוויית המשתמש באתר (LCP, FID, CLS) היא 'טובה'.

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

function assessCoreWebVitals(response) {
  // See https://web.dev/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'first_input_delay',
    '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 "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}).`)
  });
}

נקודת מפתח: ניתן להפעיל את ה-API רק עם מקור אחד או כתובת URL אחת בכל פעם. כדי לבדוק כמה אתרים או דפים צריך לבצע קריאות נפרדות ל-API.

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

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

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

מה השלב הבא?

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

• מדדים נוספים
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• מאפיינים נוספים
  • month
  • country
  • effective connection type (ECT)
• רמת פירוט גבוהה יותר
  • היסטוגרמות מפורטות
  • יותר אחוזונים

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