ממשק API של CrUX History API

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

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

רוצים לנסות?

תרחיש נפוץ לדוגמה

‏CrUX History API מאפשר להריץ שאילתות לגבי מדדי חוויית משתמש היסטוריים של URI ספציפי, כמו "קבלת המגמות ההיסטוריות של חוויית המשתמש למקור https://example.com".

ה-History API פועל לפי אותו מבנה כמו CrUX API היומי, חוץ מכך שהערכים מוצגים במערך והמפתחות מסומנים בשמות רבים (לדוגמה, histogramTimeseries במקום histogram או p75s במקום p75).

מפתח API של CrUX

בדומה ל-API היומי, כדי להשתמש ב-CrUX History API נדרש מפתח API של Google Cloud שהוקצה לשימוש ב-Chrome UX Report API. אפשר להשתמש באותו מפתח ל-API היומי ול-API ההיסטורי.

קבלה של מפתח API ושימוש בו

לחלופין, אפשר ליצור אותו בדף Credentials.

אחרי שתקבלו מפתח API, תוכלו להוסיף את פרמטר השאילתה key=yourAPIKey לכל כתובות ה-URL של הבקשות.

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

שאילתות לדוגמה

מודל נתונים

בקטע הזה מפורט המבנה של הנתונים בבקשות ובתשובות.

הקלטה

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

מזהים

המזהים מציינים אילו רשומות צריך לחפש. ב-CrUX, המזהים האלה הם דפי אינטרנט ואתרים.

מקור

כשהמזהה הוא מקור, כל הנתונים הקיימים לגבי כל הדפים במקור הזה נצברים יחד. לדוגמה, נניח למקור http://www.example.com היו דפים כפי שמפורטים ב-Sitemap הזה:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

המשמעות היא שכאשר שולחים שאילתה לדוח חוויית המשתמש ב-Chrome עם המקור שהוגדר כ-http://www.example.com, המערכת תחזיר את הנתונים של http://www.example.com/,‏ http://www.example.com/foo.html ו-http://www.example.com/bar.html, שמצטברים יחד, כי אלה כל הדפים במקור הזה.

כתובות URL

כשהמזהה הוא כתובת URL, המערכת תחזיר רק נתונים לגבי כתובת ה-URL הספציפית הזו. שוב, ב-Sitemap המקורי http://www.example.com:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

אם המזהה מוגדר לכתובת URL עם הערך http://www.example.com/foo.html, המערכת תחזיר רק נתונים לגבי הדף הזה.

מידות

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

גורם צורה

ה-API של היסטוריית CrUX זמין רק כצבירה לפי מאפיין גורם הצורה. זוהי סיווג כללי של מכשיר שמפוצל ל-PHONE, ל-TABLET ול-DESKTOP.

מדד

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

היסטוגרמות

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

היסטוגרמה של שלוש קטגוריות לדוגמה של מדד נראה כך:

{
  "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]
    }
  ],
}

הנתונים האלה מצביעים על כך ש-91.90% מהטעינות של הדפים חוו את ערך המדד לדוגמה בין 0ms ל-2,500ms בתקופה הראשונה של האיסוף בהיסטוריה, ואחריהם 92.03%, 91.94%... היחידות של המדד לא נכללות בתרשים ההיסטוגרמה הזה. במקרה הזה, נניח שמדובר במילי-שניות.

בנוסף, ב-5.21% מהטעינות של הדפים, ערך המדד לדוגמה היה בין 2,500ms ל-4,000ms בתקופה הראשונה של איסוף הנתונים בהיסטוריה, וב-2.88% מהטעינות של הדפים, הערך היה גבוה מ-4,000ms בתקופה הראשונה של איסוף הנתונים בהיסטוריה.

מאונים

המדדים עשויים לכלול גם סדרות זמן של אחוזונים שיכולות להיות שימושיות לניתוח נוסף.

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

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

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

שברים

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

דוגמה:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

בדוגמה הזו, נקודת הנתונים האחרונה מציינת ש-14.21% מהטעינות של הדפים הגיעו ממחשבים, ו-82.88% הגיעו מטלפונים.

סוגי ערכי מדדים

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

דרישות הסף למדדים

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

לדוגמה, אם בתקופה השנייה לא היו נתונים שעומדים בדרישות, זה יופיע כך:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

אם יש כתובות URL או מקורות שהסטטוס שלהם משתנה לאורך זמן, יכול להיות שתבחינו בהרבה רשומות חסרות.

תקופות איסוף

ה-CrUX History API מכיל אובייקט collectionPeriods עם מערך של שדות firstDate ו-endDate שמייצגים את תאריכי ההתחלה והסיום של כל חלון צבירת נתונים. לדוגמה:

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

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

ה-History API מתעדכן בכל יום שני ומכיל נתונים עד לשבת הקודמת (בהתאם לעיכוב הרגיל של יומיים). הוא מכיל את הנתונים מ-40 השבועות הקודמים – תקופת איסוף אחת לכל שבוע. כברירת מחדל, המערכת מחזירה 25 תקופות איסוף. כדי לשנות את הערך הזה, צריך להגדיר את "collectionPeriodCount" בבקשה למספר בין 1 ל-40.

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

שאילתות לדוגמה

שאילתות נשלחות כאובייקטים של JSON באמצעות בקשת POST אל https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=[YOUR_API_KEY]", עם נתוני השאילתה כאובייקט JSON בגוף ה-POST.

שימו לב לשימוש ב-queryHistoryRecord במקום ב-queryRecord של ה-CrUX API היומי.

דוגמה לגוף ההודעה:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

לדוגמה, אפשר להפעיל את הפקודה הזו מ-curl באמצעות שורת הפקודה הבאה (מחליפים את API_KEY במפתח שלכם):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

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

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

אם לא תגדירו את המאפיין metrics, כל המדדים הזמינים יחזרו:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (המערכת מדווחת על הערך הזה רק אם לא צוין formFactor בבקשה)

אם לא צוין ערך של formFactor, הערכים יצברו בכל גורמי הצורה.

במדריך שימוש ב-CrUX History API מפורטות שאילתה לדוגמה נוספות.

צינור עיבוד נתונים

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

הממוצע הנע

הנתונים בדוח חוויית המשתמש של Chrome הם ממוצע נע של 28 ימים של מדדים מצטברים. כלומר, הנתונים שמוצגים בדוח חוויית המשתמש ב-Chrome בכל זמן נתון הם למעשה נתונים מ-28 הימים האחרונים שנצברו יחד.

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

עדכונים שבועיים

History API מתעדכן בכל יום שני בסביבות השעה 04:00 (שעון UTC) ומכיל נתונים עד לשבת הקודמת (בהתאם למרווח הזמן הרגיל של יומיים). הוא מכיל נתונים מ-40 השבועות הקודמים (כ-10 חודשים), תקופת איסוף אחת לכל שבוע. שימו לב: כברירת מחדל, אנחנו מחזירים 25 רשומות לכל סדרת זמן, אבל אפשר לשנות את הערך הזה על ידי ציון פרמטר הבקשה collectionPeriodCount.

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

סכימה

יש נקודת קצה אחת ל-CrUX History API שמקבלת בקשות HTTP מסוג POST. ה-API מחזיר record שמכיל metrics אחד או יותר שתואם לנתוני הביצועים של המקור או הדף המבוקשים.

בקשת HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord

כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.

גוף הבקשה

ב-CrUX History API נעשה שימוש בגופים דומים של בקשות כמו ב-CrUX API היומי, עם שדה "collectionPeriodCount" אופציונלי נוסף:

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string,
  // End of list of possible types for union field url_pattern.

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

לדוגמה, כדי לבקש את ערכי ה-LCP למחשב של דף הבית של web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

הבקשה הדומה הזו כוללת את השדה האופציונלי collectionPeriodCount, והיא תספק 40 רשומות של סדרות זמן עם היסטוריית ביצועים באינטרנט של כ-10 חודשים למקור https://web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

גוף התשובה

בקשות שבוצעו בהצלחה מחזירות תגובות עם אובייקט record ו-urlNormalizationDetails במבנה הבא:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

לדוגמה, התגובה לגוף הבקשה בבקשה הקודמת עשויה להיות:

{
  "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 }
      }, {
        ...
      }
    ]
  }
}

מפתח

Key מגדיר את כל המאפיינים שמזהים את הרשומה הזו כייחודית.

{
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

מדדים

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

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

או

"fractionTimeseries": {
  object (Fractions)
}

סל

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

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

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

מאונים

Percentiles מכיל ערכים סינתטיים של מדד באחוזון סטטיסטי נתון. הן משמשות להערכת הערך של מדד מסוים מבחינת אחוז המשתמשים מתוך המספר הכולל של המשתמשים.

{
  "P75": value
}

שברים

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

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

בדומה לערכים של הצפיפות בקטגוריות של התרשים ההיסטוגרפי, כל fraction הוא מספר 0.0 <= value <= 1.0, והם מסתכמים בערך ב-1.0. אם המדד לא זמין לתקופה מסוימת של איסוף נתונים, הערך המתאים יהיה 'NaN' בכל המערכים של הפלחים.

UrlNormalization

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

{
  "originalUrl": string,
  "normalizedUrl": string
}

הגבלות קצב

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