نحوه استفاده از CrUX History API

Johannes Henkel

Jasmine Yan

Barry Pollard

منتشر شده: ۷ فوریه ۲۰۲۳، آخرین به‌روزرسانی: ۱۱ آوریل ۲۰۲۵

این راهنما، رابط برنامه‌نویسی کاربردی تاریخچه‌ی گزارش تجربه‌ی کاربری کروم (CrUX) را معرفی می‌کند که سری‌های زمانی داده‌های عملکرد وب را ارائه می‌دهد. این داده‌ها به صورت هفتگی به‌روزرسانی می‌شوند و به شما امکان می‌دهند تاریخچه‌ی حدود ۶ ماه را مشاهده کنید، که شامل ۴۰ نقطه داده است که با فاصله‌ی یک هفته از هم قرار گرفته‌اند.

وقتی از به‌روزرسانی‌های روزانه از رابط برنامه‌نویسی کاربردی اصلی CrUX استفاده شود، اکنون می‌توانید به سرعت جدیدترین داده‌ها و آنچه قبلاً اتفاق افتاده است را مشاهده کنید، که این ابزار را به ابزاری قدرتمند برای مشاهده تغییرات صفحه وب در طول زمان تبدیل می‌کند.

API موجود در این صفحه را امتحان کنید

امتحانش کن!

کوئری روزانه از API CrUX

برای خلاصه کردن از مقاله قبلی در مورد API CrUX ، می‌توانید به این روش یک تصویر لحظه‌ای از داده‌های فیلد برای یک مبدا خاص دریافت کنید:

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

این تصویر شامل مقادیر چگالی هیستوگرام و مقادیر صدک برای یک دوره جمع‌آوری ۲۸ روزه خاص، در این مورد، از ۲۷ دسامبر ۲۰۲۲ تا ۲۳ ژانویه ۲۰۲۳ است.

پرس و جو از API تاریخچه CrUX

برای فراخوانی نقطه پایانی history، queryRecord در URL به queryHistoryRecord در دستور curl تغییر دهید. استفاده از همان کلید API CrUX مانند فراخوانی قبلی کار خواهد کرد. collectionPeriodCount تعداد ورودی‌های سری زمانی را که باید بازگردانده شوند مشخص می‌کند؛ حداکثر ۴۰ است. اگر مشخص نشود، به طور پیش‌فرض ۲۵ است.

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

شکل کلی یک پاسخ مشابه است - اما داده‌های بسیار بیشتری وجود دارد! به جای یک نقطه داده واحد، اکنون سری‌های زمانی برای فیلدهای حاوی صدک ۷۵ (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 برای سطل ۰ تا ۲۵۰۰ میلی‌ثانیه از معیار Largest Contentful Paint (LCP) عبارت است از [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. هر یک از این چگالی‌ها در طول ورودی collectionPeriods مربوطه مشاهده شده‌اند. به عنوان مثال، چگالی پنجم، ۰.۹۱۸۳، چگالی مربوط به پنجمین دوره جمع‌آوری بود که در ۳ سپتامبر ۲۰۲۲ به پایان رسید و ۰.۹۱۸۷ چگالی در دوره‌ای بود که هفته پس از آن به پایان رسید.

به عبارت دیگر، با تفسیر آخرین ورودی‌های سری زمانی در مثال برای https://web.dev ، مشخص شد که از ۱۴ آگوست ۲۰۲۲ تا ۱۰ سپتامبر ۲۰۲۲، ۹۱.۸۷٪ از بارگذاری صفحات دارای مقادیر LCP کمتر از ۲۵۰۰ میلی‌ثانیه، ۵.۲۷٪ دارای مقادیر بین ۲۵۰۰ تا ۴۰۰۰ میلی‌ثانیه و ۲.۸۵٪ دارای مقادیر بیشتر از ۴۰۰۰ میلی‌ثانیه بوده‌اند.

به طور مشابه، یک سری زمانی برای مقادیر p75 وجود دارد: LCP p75 برای 14 آگوست 2022 تا 10 سپتامبر 2022، 1377 بوده است. این بدان معناست که برای این دوره جمع‌آوری، 75٪ از تجربیات کاربری LCP کمتر از 1377 میلی‌ثانیه و 25٪ از تجربیات کاربری LCP بیشتر از 1377 میلی‌ثانیه داشته‌اند.

در حالی که این مثال فقط ۶ ورودی سری زمانی و دوره‌های جمع‌آوری را فهرست می‌کند، پاسخ‌های API به طور پیش‌فرض ۲۵ ورودی سری زمانی و حداکثر ۴۰ ورودی را ارائه می‌دهند - زمانی که "collectionPeriodCount": 40 در درخواست مشخص شده باشد. از آنجایی که تاریخ پایان هر یک از این دوره‌های جمع‌آوری، شنبه‌هایی هستند که ۷ روز از هم فاصله دارند، با "collectionPeriodCount": 40 این ۱۰ ماه را پوشش می‌دهد.

در هر پاسخ داده شده، طول سری زمانی برای چگالی‌های دسته هیستوگرام و برای مقادیر p75 دقیقاً برابر با طول آرایه در فیلد collectionPeriods خواهد بود: بر اساس اندیس در این آرایه‌ها، یک تناظر یک به یک وجود دارد.

پرس و جو در داده‌های سطح صفحه

علاوه بر داده‌های سطح مبدا، API تاریخچه CrUX امکان دسترسی به داده‌های سطح صفحه تاریخی را نیز فراهم می‌کند. در حالی که داده‌های سطح مبدا قبلاً با استفاده از مجموعه داده‌های CrUX در BigQuery در دسترس بودند، داده‌های تاریخی سطح صفحه فقط در صورتی در دسترس بودند که سایت‌ها خودشان داده‌ها را جمع‌آوری و ذخیره می‌کردند. API جدید اکنون داده‌های سطح صفحه تاریخی را نیز آزاد می‌کند.

داده‌های سطح صفحه را می‌توان به همان روش پرس‌وجو کرد، اما با استفاده از url به جای origin در payload:

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 هستند، و بنابراین صفحات به طور خاص ممکن است سابقه تاریخی کاملی نداشته باشند. در این موارد، داده‌های "گمشده" برای چگالی‌های histogramTimeseries با "NaN" و برای percentilesTimeseries null نمایش داده می‌شوند. دلیل این تفاوت این است که چگالی‌های هیستوگرام همیشه عدد هستند، در حالی که صدک‌ها می‌توانند عدد یا رشته باشند (CLS از رشته‌ها استفاده می‌کند، حتی اگر شبیه عدد باشند).

داده‌ها را تجسم کنید

ساده‌ترین راه برای مصورسازی داده‌ها از طریق CrUX Vis است، ابزاری که به‌طور خاص برای نشان دادن قدرت CrUX History API ایجاد شده است. برای اطلاعات بیشتر به مستندات CrUX Vis مراجعه کنید.

برای اینکه خودتان نمودارهای مشابهی ایجاد کنید، ما یک نمونه Colab ایجاد کرده‌ایم. یک Colab یا «Colaboratory» به شما امکان می‌دهد پایتون را از داخل مرورگر خود بنویسید و اجرا کنید. API تاریخچه CrUX، Colab ( منبع ) از پایتون برای فراخوانی API و رسم نمودار داده‌ها استفاده می‌کند.

این Colab به شما امکان می‌دهد با پر کردن یک فرم کوتاه، نمودارهای p75، نمودارهای tri-bin، دریافت داده‌ها به صورت جدولی و مشاهده جفت درخواست و پاسخ برای CrUX API را ایجاد کنید. برای استفاده از این، نیازی به برنامه‌نویس بودن ندارید - اما مطمئناً می‌توانید به کد پایتون نگاه کنید و آن را به چیزی شگفت‌انگیز تغییر دهید! لطفاً از آن لذت ببرید و در ارائه بازخورد در مورد آنچه می‌یابید دریغ نکنید!

البته شما محدود به Colab یا Python نیستید و این فقط یک نمونه از نحوه استفاده از این API جدید است. به عنوان یک نقطه پایانی HTTP مبتنی بر JSON، API از هر فناوری قابل پرس و جو است.

نتیجه‌گیری

قبل از معرفی نقطه پایانی CrUX History API، صاحبان سایت در اطلاعات تاریخی که می‌توانستند از CrUX به دست آورند، محدود بودند. داده‌های ماهانه در سطح مبدا با استفاده از BigQuery در دسترس بودند، اما داده‌های هفتگی و همچنین داده‌های تاریخی در سطح صفحه در دسترس نبودند. صاحبان سایت می‌توانستند این داده‌ها را خودشان با استفاده از API روزانه ثبت کنند، اما اغلب نیاز به این کار تنها پس از رگرسیون در معیارها کشف می‌شد.

امید است با معرفی این API تاریخچه CrUX، صاحبان سایت درک بهتری از معیارهای در حال تغییر سایت خود داشته باشند و به عنوان ابزاری تشخیصی برای مواقع بروز مشکل، از آن استفاده کنند. اگر از API جدید استفاده می‌کنید، از بازخورد شما در گروه گوگل Chrome UX Report (Discussions) استقبال می‌شود.

تقدیرنامه‌ها

تصویر قهرمان اثر دیو هرینگ در Unsplash