דף זה תורגם על ידי Cloud Translation API.

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

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

Rick Viscomi

Shane Exterkamp

מערך הנתונים של הדוח על חוויית המשתמש ב-Chrome (CrUX) מייצג את חוויית השימוש של משתמשי Chrome אמיתיים ביעדים פופולריים באינטרנט. מאז 2017, כשמערך הנתונים שניתן לשלוח אליו שאילתות שוחרר לראשונה ב-BigQuery, נתוני השדה מ-CrUX שולבו בכלים למפתחים כמו PageSpeed Insights, לוח הבקרה של CrUX ודוח המדדים הבסיסיים של חוויית המשתמש (Core Web Vitals) ב-Search Console, ומאפשרים למפתחים למדוד את חוויית המשתמש של משתמשים אמיתיים ולעקוב אחריה. החלק שחסר כל הזמן הזה היה כלי שמספק גישה פרוגרמטית ללא תשלום לנתוני CrUX באמצעות REST. כדי לעזור לגשר על הפער הזה, אנחנו שמחים להכריז על השקת 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"}'

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

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

נקודת הקצה של כתובת ה-URL של ה-API, כולל מפתח ה-API הפרטי של מבצע הקריאה.
הכותרת Content-Type: application/json, שמציינת שגוף הבקשה מכיל JSON.
גוף הבקשה המקודד ב-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 ומעבירים את האובייקט body של הבקשה.

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/ יש 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 כדי לאשר שרק חוויות שימוש בטלפון כלולות.

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

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

בתוכנית מדדי הליבה לבדיקת חוויית המשתמש באתר מוגדרים יעדים שיעזרו לכם לקבוע אם חוויית משתמש או חלוקה של חוויות יכולות להיחשב כ'טובות'. בדוגמה הבאה, אנחנו משתמשים ב-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}).`)
  });
}

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

מה השלב הבא?

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

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

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