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

Johannes Henkel

Jasmine Yan

Barry Pollard

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

هنگامی که با به‌روزرسانی‌های روزانه از نقطه پایانی اصلی CrUX 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 مانند تماس قبلی کار خواهد کرد.

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

شکل کلی یک پاسخ مشابه است - اما داده های بسیار بیشتری وجود دارد! به جای یک نقطه داده واحد، اکنون سری های زمانی برای فیلدهای حاوی صدک 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 میلی‌ثانیه تا 4000 میلی‌ثانیه داشتند و 85/2 درصد مقادیری بیشتر از 4000 میلی‌ثانیه داشتند.

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

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

در هر پاسخ داده شده، طول سری‌های زمانی برای تراکم‌های 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 از رشته ها استفاده می کند، حتی اگر شبیه اعداد باشند).

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

بنابراین، ممکن است بپرسید چرا داده ها به این شکل شکل می گیرند؟ مشخص شد که این کار رسم نمودارها را آسان تر می کند. برای مثال، در اینجا نموداری برای مقادیر p75 برای Interaction To Next Paint (INP) برای https://web.dev آمده است:

در این نمودار خطی، هر مقدار در محور y یک مقدار p75 از سری زمانی p75s است و محور x زمان است که به عنوان lastDate برای هر دوره جمع آوری تنظیم می شود.

در اینجا نموداری برای سری زمانی bin هیستوگرام وجود دارد - که به عنوان نمودار سه‌بین شناخته می‌شود - زیرا این هیستوگرام‌ها دارای سه bin هستند.

محور x به عنوان lastDate برای هر دوره مجموعه تنظیم می شود. با این حال، این بار، محور y درصد بارگذاری صفحه است که در یک محدوده خاص برای متریک INP قرار می گیرد، که از طریق نمودار میله ای انباشته نشان داده شده است. نمودار p75 یک نمای کلی سریع ارائه می‌کند و در یک نمودار، اضافه کردن چندین معیار یا نمایش خطوط برای PHONE و DESKTOP نسبتاً آسان است. نمودار سه سطل حسی از توزیع مقادیر متریک اندازه گیری شده در هر دوره جمع آوری می دهد.

برای مثال، اگرچه نمودار p75 نشان می‌دهد که https://web.dev مقادیر INP تقریباً قابل قبولی در طول دوره مشاهده داشته است، نمودار سه‌بین نشان می‌دهد که برای بخش کوچکی از بارگذاری‌های صفحه، INP در واقع ضعیف بوده است. در هر دو نمودار، استنباط نسبتاً آسان است که یک رگرسیون عملکردی وجود دارد که از اواخر اکتبر شروع شد و تا اواسط نوامبر برطرف شد.

برای اینکه خودتان چنین نمودارهایی تولید کنید، نمونه ای از 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