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

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

{
  "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/ הוא 'טוב' נתוני 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"
  }
}

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

הערכת הביצועים של Core Web Vitals

בתוכנית מדדי הליבה לבדיקת חוויית המשתמש באתר מוגדרים יעדים שעוזרים לקבוע אם חוויית משתמש או התפלגות של חוויות יכולות להיחשב כ'טובות'. בדוגמה הבאה אנחנו משתמשים ב-CrUX API ובפונקציה CrUXApiUtil.query כדי לבדוק אם ההתפלגות של מדדי Core Web Vitals (LCP, INP, 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',
    '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 "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.

לפי התוצאות, הדף הזה עובר את המבדקים של Core Web Vitals לגבי כל שלושת המדדים.

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).

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

מה השלב הבא?

התכונות שכלולות בגרסה הראשונית של 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.