CrUX API

‫CrUX API دسترسی با تأخیر کم به داده‌های تجمیع‌شده تجربه کاربر واقعی در سطح جزئیات صفحه و مبدأ ارائه می‌دهد.

امتحان کنید!

مورد استفاده رایج

CrUX API امکان پُرسمان سنجه‌های تجربه کاربری را برای یک URI خاص مانند «دریافت سنجه‌ها برای مبدأ https://example.com» فراهم می‌کند.

کلید میانای برنامه‌سازی کاربردی CrUX

استفاده از CrUX API به کلید Google Cloud API نیاز دارد که برای استفاده از Chrome UX Report API فراهم شده باشد.

دریافت و استفاده از کلید میانای برنامه‌سازی کاربردی

یا در صفحه اطلاعات اعتباری ایجاد کنید.

پس‌از دریافت کلید میانای برنامه‌سازی کاربردی، برنامه‌تان می‌تواند پارامتر پُرسمان key=yourAPIKey را به همه نشانی‌های وب درخواست اضافه کند.

کلید API برای جاسازی در نشانی‌های وب ایمن است؛ نیازی به کدبندی ندارد.

نمونه پُرسمان‌ها را ببینید.

مدل داده

این بخش ساختار داده‌ها را در درخواست‌ها و پاسخ‌ها شرح می‌دهد.

ضبط کردن

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

شناسه‌ها

شناسه‌ها مشخص می‌کنند که کدام سوابق باید جستجو شوند. در CrUX، این شناسه‌ها صفحه‌های وب و وب‌سایت‌ها هستند.

مبدأ

وقتی شناسه مبدأ باشد، همه داده‌های موجود برای همه صفحه‌های آن مبدأ با هم جمع‌آوری می‌شوند. برای مثال، فرض کنید مبدأ http://www.example.com صفحه‌هایی دارد که در این نقشه سایت چیده شده‌اند:

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 برگردانده می‌شود و با هم تجمیع می‌شود، زیرا همه این‌ها صفحه‌هایی تحت آن مبدأ هستند.

نشانی‌های وب

وقتی شناسه نشانی وب باشد، فقط داده‌های مربوط به آن نشانی وب خاص برگردانده می‌شود. دوباره به نقشه سایت اصلی http://www.example.com نگاه می‌کنیم:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

اگر شناسه روی «نشانی وب» با مقدار http://www.example.com/foo.html تنظیم شده باشد، فقط داده‌های آن صفحه برگردانده خواهد شد.

ابعاد

ابعاد گروه خاصی از داده‌ها را شناسایی می‌کند که یک رکورد درمقابل آن تجمیع می‌شود، برای مثال ضریب شکل PHONE نشان می‌دهد که رکورد حاوی اطلاعاتی درباره بارگیری‌هایی است که در دستگاه همراه انجام شده است. هر بُعد تعداد معینی مقدار خواهد داشت و به‌طور ضمنی، مشخص نکردن آن بُعد به این معنی است که بُعد در همه مقادیر تجمیع شده است. برای مثال، مشخص نکردن ضریب شکل نشان می‌دهد که آن رکورد حاوی اطلاعاتی درباره بارگیری‌هایی است که در هر ضریب شکلی انجام شده است.

ضریب شکل

کلاس دستگاهی که کاربر نهایی برای پیمایش به صفحه استفاده کرده است. این کلاس عمومی دستگاه به PHONE، TABLET، و DESKTOP تقسیم می‌شود.

متریک

سنجه‌ها را به‌صورت تجمیع آماری، در هیستوگرام، صدک، و کسر گزارش می‌کنیم.

مقادیر نقطه شناور به ۴ رقم اعشار گرد می‌شوند (توجه داشته باشید که سنجه‌های cumulative_layout_shift به‌صورت رشته‌ای کدبندی می‌شوند، بنابراین شناور درنظر گرفته نمی‌شوند و تا ۲ رقم اعشار در رشته گزارش می‌شوند).

هیستوگرام

وقتی سنجه‌ها در هیستوگرام بیان می‌شوند، درصد بارگیری‌های صفحه را که در محدوده‌های خاصی برای آن سنجه قرار می‌گیرند نشان می‌دهیم.

هیستوگرام سه سطل برای یک سنجه نمونه به این شکل است:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

این داده‌ها نشان می‌دهد که برای ۳۸٫۱۸٪ از بار کردن‌های صفحه، سنجه نمونه بین ۰ تا ۱٬۰۰۰ میلی‌ثانیه اندازه‌گیری شده است. واحدهای سنجه در این هیستوگرام وجود ندارد، در این مورد فرض می‌کنیم میلی‌ثانیه است.

به‌علاوه، ۴۹٫۹۱٪ از بار کردن‌های صفحه مقدار سنجه‌ای بین ۱٬۰۰۰ میلی‌ثانیه و ۳٬۰۰۰ میلی‌ثانیه داشتند و ۱۱٫۹۲٪ مقدار سنجه‌ای بیشتر از ۳٬۰۰۰ میلی‌ثانیه داشتند.

صدک‌ها

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

{
  "percentiles": {
    "p75": 2063
  }
}

در این مثال، حداقل ۷۵٪ از بارگیری‌های صفحه با مقدار سنجه <= 2063 اندازه‌گیری شده است.

کسر

کسرها نشان‌دهنده درصد بارگیری‌های صفحه است که می‌توانند به روش خاصی برچسب‌گذاری شوند. در این حالت، مقادیر سنجه این برچسب‌ها هستند.

برای مثال، سنجه form_factors از یک شیء fractions تشکیل شده است که تفکیک عوامل شکل (یا دستگاه‌ها) را که پُرسمان داده‌شده پوشش می‌دهد فهرست می‌کند:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

در این مورد، ۳٫۷۷٪ از بارگیری‌های صفحه در رایانه، ۲٫۸۸٪ در رایانه لوحی، و ۹۳٫۳۵٪ در تلفن اندازه‌گیری شده است که درمجموع ۱۰۰٪ می‌شود.

انواع مقدار سنجه

نگاشت نام سنجه BigQuery

بازه زمان جمع‌آوری

از اکتبر ۲۰۲۲، CrUX API حاوی شیء collectionPeriod با فیلدهای firstDate و endDate است که تاریخ شروع و پایان پنجره انبوهش را نشان می‌دهد. برای مثال:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

این کار به درک بهتر داده‌ها کمک می‌کند و مشخص می‌کند که آیا داده‌ها برای آن روز به‌روزرسانی شده‌اند یا همان داده‌های دیروز را برمی‌گردانند.

بازه زمان جمع‌آوری در «اطلاعات آماری PageSpeed» نیز دردسترس است:

علاوه‌براین، collectionPeriod همیشه ۲۸ روز را نشان می‌دهد، حتی اگر داده‌ها مربوط به کل ۲۸ روز نباشد (برای مثال اگر صفحه‌ای کمتر از ۲۸ روز پیش راه‌اندازی شده باشد). collectionPeriod دوره زمانی‌ای است که داده‌های CrUX در آن جمع‌آوری شده است، نه لزوماً دوره زمانی‌ای که داده‌ها نشان می‌دهند.

پُرسمان‌های نمونه

پُرسمان‌ها به‌عنوان اشیاء JSON بااستفاده از درخواست POST به https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" با داده‌های پُرسمان به‌عنوان شیء JSON در بدنه POST ارسال می‌شوند:

{
  "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:queryRecord?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
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (فقط درصورتی گزارش می‌شود که هیچ formFactor در درخواست مشخص نشده باشد)
• experimental_ad_count (فقط برای صفحه‌هایی که در سنجه‌های آگهی گنجانده شده‌اند گزارش می‌شود)
• ‫experimental_ad_density (فقط برای صفحه‌هایی که در سنجه‌های آگهی گنجانده شده‌اند گزارش می‌شود)
• ‫experimental_ad_cpu (فقط برای صفحه‌هایی که در سنجه‌های آگهی گنجانده شده‌اند گزارش می‌شود)
• ‫experimental_ad_kilobytes (فقط برای صفحه‌هایی که در سنجه‌های آگهی گنجانده شده‌اند گزارش می‌شود)

اگر مقدار formFactor ارائه نشده باشد، مقادیر در همه ضرایب شکل جمع‌آوری خواهد شد.

برای نمونه پُرسمان‌های بیشتر، استفاده از Chrome UX Report API را ببینید.

خط لوله داده‌ها

مجموعه‌داده CrUX ازطریق یک خط لوله پردازش می‌شود تا داده‌ها قبل‌از دردسترس قرار گرفتن بااستفاده از API، تجمیع، فیلتر، و یکپارچه شوند.

میانگین متحرک

داده‌های «گزارش تجربه کاربری Chrome» میانگین متحرک ۲۸ روزه از سنجه‌های انبوهش‌شده است. این یعنی داده‌های ارائه‌شده در Chrome UX Report در هر زمان مشخص درواقع داده‌های ۲۸ روز گذشته است که باهم انبوهش شده‌اند.

این شبیه به نحوه جمع‌آوری گزارش‌های ماهانه توسط مجموعه‌داده CrUX در BigQuery است.

به‌روزرسانی‌های روزانه

داده‌ها هر روز حدود ساعت ۰۴:۰۰ به‌وقت ساعت هماهنگ جهانی به‌روزرسانی می‌شود. هیچ قرارداد سطح خدماتی برای زمان‌های به‌روزرسانی وجود ندارد؛ این کار هر روز براساس بهترین تلاش ممکن انجام می‌شود.

طرح

یک نقطه پایانی برای CrUX API وجود دارد که درخواست‌های POST HTTP را می‌پذیرد. ‫API یک record برمی‌گرداند که حاوی یک یا چند metrics مربوط به داده‌های عملکرد درباره مبدأ یا صفحه درخواست‌شده است.

درخواست HTTP

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

نشانی وب از نحو ترانویسی gRPC استفاده می‌کند.

متن درخواست

بدنه درخواست باید حاوی داده‌هایی با ساختار زیر باشد:

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

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

برای مثال، برای درخواست مقادیر «رنگ‌آمیزی محتوای اصلی بزرگ‌ترین» صفحه اصلی مستندات توسعه‌دهندگان Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

متن پاسخ

درخواست‌های موفق پاسخ‌هایی با شیء record و urlNormalizationDetails در ساختار زیر برمی‌گردانند:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

برای مثال، پاسخ به بدنه درخواست در درخواست قبلی می‌تواند این باشد:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

کلید

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

سنجه‌ها

metric مجموعه‌ای از داده‌های تجربه کاربری تجمیع‌شده برای یک سنجه عملکرد وب، مثل «اولین نقاشی محتوایی» است. ممکن است حاوی هیستوگرام خلاصه استفاده واقعی از Chrome به‌صورت مجموعه‌ای از bins، داده‌های صدک خاص (مثل p75)، یا ممکن است حاوی کسرهای برچسب‌گذاری‌شده باشد.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

یا

{
  "fractions": {
    object (Fractions)
  }
}

سطل زباله

bin بخش مجزایی از داده است که از ابتدا تا انتها را دربرمی‌گیرد، یا اگر انتهایی برای آن مشخص نشده باشد، از ابتدا تا بی‌نهایت مثبت را دربرمی‌گیرد.

مقادیر شروع و پایان یک دسته در نوع مقدار سنجه‌ای که نشان می‌دهد ارائه می‌شود. برای مثال، اولین رنگ‌آمیزی محتوایی برحسب میلی‌ثانیه اندازه‌گیری می‌شود و به‌صورت عدد صحیح نمایش داده می‌شود، بنابراین سطل‌های سنجه آن از int32 برای انواع شروع و پایان خود استفاده خواهند کرد. بااین‌حال، تغییر چیدمان تجمعی با اعشار بدون واحد اندازه‌گیری می‌شود و به‌صورت اعشار کدگذاری‌شده به‌عنوان رشته نمایش داده می‌شود، بنابراین دسته‌های سنجه آن از رشته‌ها برای نوع مقدار خود استفاده خواهند کرد.

{
  "start": value,
  "end": value,
  "density": number
}

صدک‌ها

Percentiles حاوی مقادیر ترکیبی یک سنجه در صدک آماری مشخصی است. این‌ها برای تخمین مقدار سنجه‌ای که درصدی از کاربران از کل تعداد کاربران تجربه کرده‌اند استفاده می‌شود.

{
  "P75": value
}

کسر

‫Fractions حاوی کسرهای برچسب‌گذاری‌شده‌ای است که مجموع آن‌ها تقریباً ۱ می‌شود. هر برچسب به نحوی بار کردن صفحه را توصیف می‌کند، بنابراین سنجه‌هایی که به این روش نشان داده می‌شوند را می‌توان به‌صورت تولید مقادیر متمایز به‌جای مقادیر عددی درنظر گرفت، و کسرها بیانگر این هستند که یک مقدار متمایز خاص چند بار اندازه‌گیری شده است.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

درست مانند مقادیر چگالی در سطل‌های هیستوگرام، هر fraction عددی 0.0 <= value <= 1.0 است و مجموع آن‌ها تقریباً ۱٫۰ می‌شود.

UrlNormalization

شیء نشان‌دهنده کنش‌های عادی‌سازی انجام‌شده برای عادی‌سازی نشانی وب برای دستیابی به شانس بالاتر جستجوی موفق. این تغییرات، تغییراتی ساده و خودکار هستند که وقتی مشخص شود جستجوی url_pattern ارائه‌شده ناموفق خواهد بود، اعمال می‌شوند. کنش‌های پیچیده مانند دنبال کردن تغییرمسیرها انجام نمی‌شود.

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

محدودیت‌های نرخ

‫CrUX API به ۱۵۰ پُرسمان در دقیقه برای هر پروژه Google Cloud محدود شده است که بدون هزینه ارائه می‌شود. این حد و استفاده فعلی‌تان را می‌توانید در کنسول Google Cloud ببینید. این سهمیه سخاوتمندانه باید برای اکثریت قریب به اتفاق موارد استفاده کافی باشد و امکان پرداخت هزینه برای افزایش سهمیه وجود ندارد.