ממשק API של CrUX History API

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

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

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

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

מפתח API של CrUX

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

אפשר ליצור חשבון בדף פרטי כניסה ולהקצות אותו לשימוש של Chrome UX Report API.

אחרי שיש לכם מפתח API, האפליקציה יכולה לצרף את פרמטר השאילתה key=[YOUR_API_KEY] לכל כתובות ה-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 מציין שהרשומה מכילה מידע על טעינות שבוצעו במכשיר נייד.

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

המדד

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

היסטוגרמות

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

היסטוגרמה פשוטה של שלושה bin עבור מדד לדוגמה נראית כך:

{
  "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% מטעינות הדפים נמצא ערך המדד לדוגמה בין 0 אלפיות השנייה ל-2,500 אלפיות שנייה, בתקופת האיסוף הראשונה בהיסטוריה, ואחריה 92.03%, 91.94%... יחידות המדד לא נכללות בהיסטוגרמה הזו. במקרה הזה נניח אלפיות השנייה.

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

אחוזונים

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

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

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

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

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

חשוב לשים לב שהשימוש ב-queryHistoryRecord מחליף את queryRecord של ממשק ה-API היומי של CrUX.

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

{
  "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
• first_input_delay
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• navigation_types
• round_trip_time
• form_factors (מדווח רק אם לא צוין formFactor בבקשה)

אם לא תספקו ערך של formFactor, הערכים יצטברו באופן מצטבר מכל גורמי הצורה.

תוכלו למצוא עוד שאילתות לדוגמה במדריך שימוש ב-CrUX History API.

צינור נתונים

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

הממוצע הנע

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

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

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

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

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

סכימה

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

בקשת HTTP

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

בכתובת ה-URL נעשה שימוש בתחביר המרת קידוד של gRPC.

גוף הבקשה

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

לדוגמה, כדי לבקש את ערכי Largest Contentful Paint (LCP) בדף הבית של web.dev במחשב:

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

גוף התשובה

בקשות שבוצעו בהצלחה מחזירות תשובות עם אובייקט 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.
}

שדות
formFactor	enum (FormFactor) גורם הצורה הוא סוג המכשיר שבו השתמשו כל המשתמשים כדי לגשת לאתר עבור הרשומה הזו. אם גורם הצורה לא צוין, יוחזרו נתונים נצברים מכל גורמי הצורה.
שדה איחוד url_pattern. תבנית ה-URL היא כתובת ה-URL שהרשומה חלה עליה. url_pattern יכול להיות רק אחת מהאפשרויות הבאות:
origin	string המקור מציין את המקור שעבורו מיועדת הרשומה. הערה: כשמציינים מקור, הנתונים של טעינות מתחת למקור הזה בכל הדפים נצברים לנתוני חוויית המשתמש ברמת המקור.
url	string url מציין כתובת URL ספציפית עבור הרשומה הזו. הערה: כשמציינים ערך מסוג url בלבד לגבי כתובת ה-URL הספציפית הזו, הנתונים נצברים.

מדדים

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

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

או

"fractionTimeseries": {
  object (Fractions)
}

שדות
histogramTimeseries[]	object (Bin) ההיסטוגרמה של זמני (Timeeries) של חוויות המשתמש עבור מדד. ההיסטוגרמה של זמני (timeeries) תכלול לפחות סל אחד, והצפיפות של כל התאים מסוכמת ל-1 בערך. ערכים חסרים בתקופת האיסוף הספציפית הזו יסומנו כ-"NaN".
percentilesTimeseries	object (Percentiles) אחוזונים שימושיים נפוצים של המדד. סוג הערך של האחוזונים יהיה זהה לסוגי הערכים שניתנו עבור פחי ההיסטוגרמה. ערכים חסרים בתקופת האיסוף הספציפית הזו יסומנו כ-null.
fractionTimeseries	object (Fractions) אובייקט זה מכיל זמני טעינה של שברים מתויגים. הערכים מסתכמים בערך 1 לכל רשומה. השברים יעוגלו ל-4 ספרות אחרי הנקודה העשרונית. ערכים חסרים מבוטאים כ-'NaN' בכל השברים.

סל

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

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

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

שדות
start	(integer | string) Start הוא ההתחלה של סל הנתונים.
end	(integer | string) End הוא הסוף של סל הנתונים. אם סוף לא מאוכלס, לסל אין סוף והוא תקין מההתחלה עד +inf.
densities	array[number] זמנים של שיעור המשתמשים שקיבלו את הערך של סל המודעות הזה עבור המדד הנתון. הצפיפות תעוגל ל-4 ספרות אחרי הנקודה העשרונית.

אחוזונים

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

{
  "P75": value
}

שדות
p75s	array[(integer | string)] זמני הטעינה של הערכים ש-75% מהטעינות של הדפים כללו את המדד הנתון באותו ערך או פחות ממנו.

שברים

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' בכל מערכי שברים.

שדות
p75s	array[(integer | string)] בזמנים שבהם הערך הזה מופיע ב-75% מהטעינות של הדפים, המדד הזה זהה לערך הזה או נמוך ממנו.

UrlNormalization

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

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

שדות
originalUrl	string כתובת ה-URL המקורית המבוקשת לפני פעולות נירמול.
normalizedUrl	string כתובת ה-URL אחרי פעולות נירמול. זוהי כתובת URL חוקית של חוויית משתמש שניתן לחפש אותה באופן סביר.

מגבלות קצב של יצירת בקשות

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