ממשק API של CrUX History API

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 מחייב מפתח Google Cloud API מוקצה לשימוש ב-Chrome UX Report API. ניתן להשתמש באותו מפתח גם עבור ה-API היומי וגם עבור ה-API להיסטוריה.

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

לקבלת מפתח

אפשר גם ליצור כרטיס בדף פרטי כניסה.

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

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

מדד

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

היסטוגרמות

כאשר מדדים מבוטאים במערך היסטוגרמה, כל ערך של Timeeries מייצג את האחוז טעינה של דפים שבהם המדד נכנס למרווח זמן באופן יחסי לכולם. הנקודות על הגרף מוצגות לפי סדר התאריכים של תקופת האיסוף שהוחזר גם על ידי ה-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
• 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 משתמשת בתחביר של Transcoding של gRPC.

גוף הבקשה

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

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