CrUX API

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

امتحان کنید!

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

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

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

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

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

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

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

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

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

مدل داده

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

ضبط کردن

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

شناسه‌ها

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

مبدأ

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

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

این یعنی هنگام جستجو در Chrome UX Report با مبدأ تنظیم‌شده روی 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

اگر شناسه روی URL با مقدار 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_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• 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 را می‌پذیرد. ‫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 Console ببینید. این سهمیه سخاوتمندانه باید برای اکثریت قریب به اتفاق موارد استفاده کافی باشد و امکان پرداخت هزینه برای افزایش سهمیه وجود ندارد.