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

Johannes Henkel
Johannes Henkel
X GitHub Mastodon
Jasmine Yan
Jasmine Yan
GitHub
Barry Pollard

תאריך פרסום: 7 בפברואר 2023, תאריך עדכון אחרון: 11 באפריל 2025

במדריך הזה נסביר על נקודת הקצה History API של דוח חוויית המשתמש ב-Chrome‏ (CrUX), שמספקת סדרות זמן של נתוני ביצועים באינטרנט. הנתונים האלה מתעדכנים מדי שבוע ומאפשרים לכם לראות היסטוריה של כ-6 חודשים, עם 40 נקודות נתונים שמרווחות ביניהם שבוע.

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

ניסיון ב-API בדף הזה

רוצים לנסות?

שליחת שאילתה ל-CrUX API היומי

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

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"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

תמונת המצב הזו כוללת ערכים של צפיפות היסטוגרמה וערכים של אחוזונים בתקופה מסוימת של 28 יום, במקרה הזה מ-27 בדצמבר 2022 עד 23 בינואר 2023.

שליחת שאילתה ל-CrUX History API

כדי לקרוא לנקודת הקצה של ההיסטוריה, משנים את queryRecord בכתובת ה-URL ל-queryHistoryRecord בפקודה curl. אפשר להשתמש באותו מפתח API של CrUX כמו בקריאה הקודמת. collectionPeriodCount מציין את מספר הרשומות של סדרות הזמן שיש להחזיר. המספר המקסימלי הוא 40. אם לא מציינים ערך, ערך ברירת המחדל הוא 25.

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

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

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377
          ]
        }
      }
      // ...
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]
  }
}

בדוגמה הזו, סדרת הזמן densities של הקטגוריה 0 עד 2,500 אלפיות השנייה של המדד Largest Contentful Paint‏ (LCP) היא [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. כל אחת מהצפיפות האלה נצפתה במהלך הערך המתאים של collectionPeriods. לדוגמה, הצפיפות החמישית, 0.9183, הייתה הצפיפות בתקופה החמישית של איסוף הנתונים, שהסתיימה ב-3 בספטמבר 2022, ו-0.9187 הייתה הצפיפות בתקופה שהסתיימה בשבוע שלאחר מכן.

במילים אחרות, לפי פרטי הרשומה האחרונים בסדרת הזמן בדוגמה של https://web.dev, נמצא שבתקופה שבין 14 באוגוסט 2022 ל-10 בספטמבר 2022, ל-91.87% מהטעינות של הדפים היו ערכים של LCP שנמוכים מ-2,500ms, ל-5.27% היו ערכים בין 2,500ms ל-4,000ms ול-2.85% היו ערכים גבוהים מ-4,000ms.

באופן דומה, יש סדרה זמנית של ערכי p75: ערך p75 של LCP מ-14 באוגוסט 2022 עד 10 בספטמבר 2022 היה 1377. כלומר, בתקופה הזו של איסוף הנתונים, 75% מחוויית המשתמשים היו עם LCP של פחות מ-1,377 אלפיות השנייה, ו-25% מחוויית המשתמשים היו עם LCP של יותר מ-1,377 אלפיות השנייה.

בדוגמה מפורטים רק 6 רשומות של סדרות זמנים ותקופות איסוף, אבל התשובות מה-API מספקות 25 רשומות של סדרות זמנים כברירת מחדל, ו-40 רשומות לכל היותר – כשהערך "collectionPeriodCount": 40 מצוין בבקשה. מאחר שתאריכי הסיום של כל תקופת איסוף הם ימי שבת שמפרידים ביניהם 7 ימים, בעזרת "collectionPeriodCount": 40 אפשר לקבל נתונים מ-10 חודשים.

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

שליחת שאילתות לנתונים ברמת הדף

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

אפשר לשלוח שאילתה לגבי הנתונים ברמת הדף באותו אופן, אבל להשתמש ב-url במקום ב-origin בתוכן המטען:

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

נתונים היסטוריים ברמת הדף (וברמת המקור) כפופים לאותן דרישות סף כמו שאר הנתונים ב-CrUX, ולכן יכול להיות שלדפים מסוימים לא תהיה היסטוריה מלאה. במקרים כאלה, הנתונים 'החסרים' יוצגו כ-"NaN" עבור הצפיפויות histogramTimeseries וכ-null עבור percentilesTimeseries. הסיבה להבדל היא שצפיפות ההיסטוגרמה תמיד מספרים, בעוד שפרמטרים של אחוזונים יכולים להיות מספרים או מחרוזות (CLS משתמש במחרוזות, גם אם הן נראות כמו מספרים).

המחשה חזותית של הנתונים

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

כדי ליצור תרשימים דומים בעצמכם, יצרנו דוגמה ב-Colab. ‫Colab, או Colaboratory, הוא מוצר שמאפשר לכתוב קוד Python ולהריץ אותו בדפדפן. ב-CrUX History API Colab (מקור) נעשה שימוש ב-Python כדי לבצע קריאות ל-API ולתעד את הנתונים בתרשים.

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

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

סיכום

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

אנחנו מקווים שהשקת CrUX History API תאפשר לבעלי אתרים להבין טוב יותר את השינויים במדדי האתר שלהם, וככלי אבחון במקרה של בעיות. אם אתם משתמשים ב-API החדש, נשמח לקבל מכם משוב בקבוצת Google‏ דוח UX של Chrome (דיונים).

תודות

תמונה ראשית (Hero) של Dave Herring ב-Unsplash