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

Johannes Henkel

Jasmine Yan

Barry Pollard

تاریخ انتشار: 7 فوریه 2023، آخرین به روز رسانی: 11 آوریل 2025

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

هنگامی که با به‌روزرسانی‌های روزانه از نقطه پایانی اصلی 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 تغییر دهید. استفاده از همان کلید CrUX API مانند تماس قبلی کار خواهد کرد. 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 تا 2500 میلی‌ثانیه متریک بزرگترین رنگ محتوایی (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 کوچک‌تر از 2500 میلی‌ثانیه، 5.27 درصد دارای مقادیر بین 2500 میلی‌ثانیه بزرگ‌تر و 40200 میلی‌ثانیه‌تر و 4 درصد دارای مقادیر بزرگ‌تر از 5000 میلی‌ثانیه بوده است. 4000 میلی‌ثانیه

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

در حالی که مثال فقط 6 ورودی سری زمانی و دوره های جمع آوری را فهرست می کند، پاسخ های API به طور پیش فرض 25 ورودی سری زمانی و حداکثر 40 را ارائه می دهد - زمانی که "collectionPeriodCount": 40 در درخواست مشخص شده است. از آنجایی که تاریخ پایان هر یک از این دوره‌های جمع‌آوری، شنبه‌هایی است که 7 روز فاصله دارند، با "collectionPeriodCount": 40 این 10 ماه را پوشش می‌دهد.

در هر پاسخ داده شده، طول سری های زمانی برای تراکم bin هیستوگرام و برای مقادیر 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" به شما امکان می دهد پایتون را از داخل مرورگر خود بنویسید و اجرا کنید. CrUX History API Colab ( منبع ) از پایتون برای برقراری تماس با API و نمودار داده ها استفاده می کند.

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

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

نتیجه گیری

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

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

قدردانی ها

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