CrUX API به دادههای تجربه کاربر واقعی انباشته شده در جزئیات صفحه و مبدا دسترسی با تأخیر کم میدهد.
مورد استفاده رایج
CrUX API امکان پرس و جو از معیارهای تجربه کاربر را برای یک URI خاص مانند "دریافت معیارها برای مبدا https://example.com
" فراهم می کند.
کلید CrUX API
استفاده از CrUX API به یک کلید Google Cloud API نیاز دارد که برای استفاده از Chrome UX Report API
ارائه شده است.
به دست آوردن و استفاده از یک کلید API
یک کلید دریافت کنیدیا در صفحه اعتبارنامه ایجاد کنید.
بعد از اینکه یک کلید API داشتید، برنامه شما می تواند پارامتر query key= yourAPIKey
به همه URL های درخواستی اضافه کند.
کلید API برای جاسازی در URL ها ایمن است. به هیچ کدگذاری نیاز ندارد.
به نمونه سوالات مراجعه کنید.
مدل داده
این بخش به جزئیات ساختار داده ها در درخواست ها و پاسخ ها می پردازد.
ضبط کنید
یک قطعه اطلاعات مجزا در مورد یک صفحه یا سایت. یک رکورد می تواند داده هایی داشته باشد که برای یک شناسه و برای ترکیب خاصی از ابعاد خاص است. یک رکورد می تواند حاوی داده هایی برای یک یا چند معیار باشد.
شناسه ها
شناسه ها مشخص می کنند که چه رکوردهایی باید جستجو شوند. در CrUX این شناسه ها صفحات وب و وب سایت ها هستند.
مبدا
هنگامی که شناسه یک مبدا باشد، تمام داده های موجود برای همه صفحات در آن مبدا با هم جمع می شوند. به عنوان مثال، بگویید مبدا http://www.example.com
دارای صفحاتی است که توسط این نقشه سایت مشخص شده است:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
این بدان معناست که هنگام جستجو در گزارش Chrome UX با مبدا تنظیم شده روی http://www.example.com
، دادههای http://www.example.com/
، http://www.example.com/foo.html
و http://www.example.com/bar.html
بازگردانده میشوند، با هم جمع میشوند، زیرا همه صفحات تحت آن مبدا هستند.
URL ها
وقتی شناسه یک URL باشد، فقط دادههای آن URL خاص برگردانده میشود. نگاهی دوباره به نقشه سایت مبدا 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
تقسیم می شود.
متریک
ما معیارها را به عنوان تجمعات آماری، در هیستوگرام، صدک، و کسری گزارش می کنیم.
مقادیر ممیز شناور به 4 رقم اعشار گرد می شوند (توجه داشته باشید که معیارهای cumulative_layout_shift
دو برابر به عنوان یک رشته کدگذاری می شوند، بنابراین شناورها در نظر گرفته نمی شوند و به 2 رقم اعشار در رشته گزارش می شوند).
هیستوگرام
وقتی معیارها در یک هیستوگرام بیان میشوند، درصد بارگذاری صفحه را در محدودههای خاصی برای آن متریک نشان میدهیم.
یک هیستوگرام سه بن برای یک متریک نمونه به این صورت است:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
این دادهها نشان میدهد که برای 38.18 درصد از بارگذاریهای صفحه، متریک نمونه بین 0 میلیثانیه تا 1000 میلیثانیه اندازهگیری شده است. واحدهای متریک در این هیستوگرام موجود نیستند، در این حالت ما میلی ثانیه را فرض می کنیم.
علاوه بر این، 49.91 درصد از بارگیریهای صفحه، مقدار متریک بین 1000 میلیثانیه تا 3000 میلیثانیه را مشاهده کردند و 11.92 درصد مقداری بیشتر از 3000 میلیثانیه را مشاهده کردند.
صدک ها
متریک ها همچنین ممکن است حاوی صدک هایی باشند که می توانند برای تجزیه و تحلیل اضافی مفید باشند. ما مقادیر متریک خاصی را در صدک معین برای آن متریک گزارش میکنیم. آنها بر اساس مجموعه کامل دادههای موجود هستند و نه دادههای binned نهایی، بنابراین لزوماً با یک صدک درونیابی که بر اساس هیستوگرام binned نهایی است مطابقت ندارند.
{
"percentiles": {
"p75": 2063
}
}
در این مثال، حداقل 75 درصد از بارگذاری صفحه با مقدار متریک <= 2063
اندازه گیری شد.
کسری
کسری نشان دهنده درصد بارگذاری صفحه است که می تواند به روشی خاص برچسب گذاری شود. در این مورد، مقادیر متریک این برچسب ها هستند.
برای مثال، متریک form_factors
شامل یک شی fractions
است که تفکیک فاکتورهای فرم (یا دستگاههایی) را که کوئری داده شده پوشش میدهد، فهرست میکند:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
در این مورد، 3.77 درصد از بارگذاری صفحه در دسکتاپ، 2.88 درصد در رایانه لوحی و 93.35 درصد در تلفن اندازه گیری شد که در کل 100 درصد است.
انواع مقادیر متریک
نام متریک CrUX API | نوع داده | واحدهای متریک | تجمیع آماری | مستندات |
---|---|---|---|---|
cumulative_layout_shift | 2 رقم اعشار دو برابر به عنوان رشته رمزگذاری شده است | بدون واحد | هیستوگرام با سه سطل، صدک با p75 | cls |
first_contentful_paint | بین المللی | میلی ثانیه | هیستوگرام با سه سطل، صدک با p75 | fcp |
interaction_to_next_paint | بین المللی | میلی ثانیه | هیستوگرام با سه سطل، صدک با p75 | ورودی |
largest_contentful_paint | بین المللی | میلی ثانیه | هیستوگرام با سه سطل، صدک با p75 | lcp |
experimental_time_to_first_byte | بین المللی | میلی ثانیه | هیستوگرام با سه سطل، صدک با p75 | ttfb |
form_factors | 4 اعشاری جای دوتایی | درصد | نگاشت از ضریب فرم به کسری | عوامل شکل |
navigation_types | 4 اعشاری جای دوتایی | درصد | نقشه برداری از نوع ناوبری به کسری | انواع ناوبری |
round_trip_time | بین المللی | میلی ثانیه | صدک با p75 | rtt |
نگاشت نام متریک BigQuery
نام متریک CrUX API | نام متریک BigQuery |
---|---|
cumulative_layout_shift | layout_instability.cumulative_layout_shift |
first_contentful_paint | first_contentful_paint |
interaction_to_next_paint | interaction_to_next_paint |
largest_contentful_paint | largest_contentful_paint |
experimental_time_to_first_byte | experimental.time_to_first_byte |
navigation_types | navigation_types |
form_factors | n/a |
round_trip_time | n/a |
دوره جمع آوری
از اکتبر 2022، CrUX API حاوی یک شی collectionPeriod
با فیلدهای firstDate
و endDate
است که تاریخ شروع و پایان پنجره تجمع را نشان می دهد. به عنوان مثال:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
این اجازه می دهد تا درک بهتری از داده ها و اینکه آیا هنوز برای آن روز به روز شده است یا همان داده های دیروز را برمی گرداند.
توجه داشته باشید که CrUX API تقریباً دو روز از تاریخ امروز عقبتر است، زیرا منتظر دادههای تکمیلشده برای آن روز است، و قبل از اینکه در API در دسترس قرار گیرد، مدتی زمان پردازش وجود دارد. منطقه زمانی مورد استفاده، ساعت استاندارد اقیانوس آرام (PST) است، بدون تغییر برای صرفه جویی در روز.
پرس و جوهای نمونه
پرس و جوها به عنوان اشیاء 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
-
navigation_types
-
form_factors
(فقط در صورتی گزارش شود که هیچformFactor
در درخواست مشخص نشده باشد)
اگر مقدار formFactor
ارائه نشود، مقادیر در تمام عوامل فرم جمع می شوند.
برای نمونه سوالات بیشتر به استفاده از Chrome UX Report API مراجعه کنید.
خط لوله داده
مجموعه داده CrUX از طریق یک خط لوله پردازش می شود تا داده ها را قبل از در دسترس قرار گرفتن با استفاده از API ادغام، تجمیع و فیلتر کند.
میانگین چرخشی
دادههای گزارش Chrome UX میانگین چرخشی 28 روزه از معیارهای جمعآوری شده است. این بدان معنی است که دادههای ارائه شده در گزارش Chrome UX در هر زمان معین، در واقع دادههای 28 روز گذشته است که با هم جمع شدهاند.
این شبیه به نحوه جمعآوری گزارشهای ماهانه توسط مجموعه داده CrUX در BigQuery است.
به روز رسانی روزانه
داده ها هر روز حدود ساعت 04:00 UTC به روز می شوند. هیچ توافقنامه سطح خدمات برای زمان به روز رسانی وجود ندارد. هر روز بر اساس بهترین تلاش اجرا می شود.
طرحواره
یک نقطه پایانی برای CrUX API وجود دارد که درخواستهای POST
HTTP را میپذیرد. API record
را برمیگرداند که حاوی یک یا چند metrics
مربوط به دادههای عملکرد در مورد مبدا یا صفحه درخواستی است.
درخواست HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
URL از دستور GRPC Transcoding استفاده می کند.
درخواست بدن
بدنه درخواست باید حاوی داده هایی با ساختار زیر باشد:
{
"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.
}
فیلدها | |
---|---|
formFactor | فاکتور فرم یک بعد پرس و جو است که کلاس دستگاهی را که داده های رکورد باید به آن تعلق داشته باشد را مشخص می کند. این فیلد از مقادیر توجه: اگر هیچ فاکتور فرمی مشخص نشده باشد، یک رکورد ویژه با داده های انباشته روی تمام فاکتورهای فرم برگردانده می شود. |
metrics[] | معیارهایی که باید در پاسخ گنجانده شود. اگر هیچ یک مشخص نشده باشد، هر معیاری که پیدا شده است برگردانده می شود. مقادیر مجاز: |
url_ pattern فیلد اتحادیه. url_pattern شناسه اصلی برای جستجوی رکورد است. می تواند تنها یکی از موارد زیر باشد: | |
origin | مثالها: |
url | مثالها: |
به عنوان مثال، برای درخواست بزرگترین مقادیر رنگ محتوا برای دسکتاپ برای صفحه اصلی اسناد برنامهنویس 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.
}
فیلدها | |
---|---|
formFactor | فرم فاکتور کلاس دستگاهی است که همه کاربران برای دسترسی به سایت برای این رکورد از آن استفاده کردند. اگر فاکتور فرم نامشخص باشد، داده های انباشته شده روی همه فاکتورهای فرم بازگردانده می شود. |
url_ pattern فیلد اتحادیه. الگوی URL آدرسی است که رکورد روی آن اعمال می شود. url_ pattern می تواند تنها یکی از موارد زیر باشد: | |
origin | توجه: هنگام تعیین |
url | توجه: هنگام تعیین یک |
معیارها
metric
مجموعهای از دادههای تجمیع تجربه کاربر برای یک معیار عملکرد وب است، مانند اولین رنگ محتوا. ممکن است حاوی یک هیستوگرام خلاصه از استفاده از کروم در دنیای واقعی بهعنوان مجموعهای از bins
، دادههای صدک خاص (مانند p75)، یا ممکن است شامل کسرهای برچسبگذاری شده باشد.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
یا
{
"fractions": {
object (Fractions)
}
}
فیلدها | |
---|---|
histogram[] | هیستوگرام تجربیات کاربر برای یک متریک. هیستوگرام حداقل یک سطل خواهد داشت و چگالی همه سطل ها برابر با 1 می شود. |
percentiles | صدک های مفید رایج متریک. نوع مقدار برای صدک ها مانند انواع مقادیر داده شده برای bin های هیستوگرام خواهد بود. |
fractions | این شی شامل کسرهای برچسبگذاری شده است که مجموع آنها 1~ میشود. کسرها به 4 رقم اعشار گرد می شوند. |
بن
bin
یک بخش مجزا از داده است که از ابتدا تا انتها را شامل می شود، یا اگر پایانی از ابتدا تا بی نهایت مثبت داده نشود.
مقادیر شروع و پایان یک bin در نوع مقدار معیاری که نشان می دهد داده می شود. به عنوان مثال، اولین رنگ پر محتوا در میلی ثانیه اندازه گیری می شود و به صورت int در معرض دید قرار می گیرد، بنابراین سطل های متریک آن از int32 برای انواع ابتدایی و انتهایی آن استفاده می کنند. با این حال، تغییر چیدمان تجمعی در اعشار بدون واحد اندازهگیری میشود و به صورت اعشاری رمزگذاری شده بهعنوان یک رشته در معرض نمایش قرار میگیرد، بنابراین سطلهای متریک آن از رشتهها برای نوع مقدار آن استفاده میکنند.
{
"start": value,
"end": value,
"density": number
}
فیلدها | |
---|---|
start | Start ابتدای سطل داده است. |
end | End انتهای سطل داده است. اگر end پر نشده باشد، بن پایانی ندارد و از ابتدا تا +inf معتبر است. |
density | نسبت کاربرانی که مقدار این سطل را برای معیار داده شده تجربه کردند. تراکم ها به 4 رقم اعشار گرد می شوند. |
صدک ها
Percentiles
حاوی مقادیر ترکیبی یک متریک در یک صدک آماری معین است. اینها برای تخمین مقدار یک معیار که توسط درصدی از کاربران از تعداد کل کاربران تجربه شده است، استفاده می شود.
{
"P75": value
}
فیلدها | |
---|---|
p75 | 75 درصد از بارگیریهای صفحه، معیار داده شده را در یا کمتر از این مقدار تجربه کردند. |
کسری
Fractions
شامل کسرهای برچسبگذاریشده است که مجموع آنها به 1 ~ میرسد. هر برچسب به نحوی بار صفحه را توصیف میکند، بنابراین معیارهایی که به این روش نشان داده میشوند را میتوان بهعنوان تولید مقادیر متمایز به جای مقادیر عددی در نظر گرفت، و کسریها بیان میکنند که یک مقدار متمایز به دفعات اندازهگیری شده است.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
تقریباً مانند مقادیر چگالی در سطل های هیستوگرام، هر fraction
یک عدد 0.0 <= value <= 1.0
است و جمع آنها به ~1.0 می رسد.
UrlNormalization
شی نشان دهنده اقدامات عادی سازی انجام شده برای عادی سازی URL برای دستیابی به شانس بالاتری برای جستجوی موفقیت آمیز است. اینها تغییرات خودکار ساده ای هستند که هنگام جستجوی url_pattern
ارائه شده انجام می شود که ناموفق است. اقدامات پیچیده مانند تغییر مسیرهای زیر انجام نمی شود.
{
"originalUrl": string,
"normalizedUrl": string
}
فیلدها | |
---|---|
originalUrl | URL اصلی درخواست شده قبل از هر اقدام عادی سازی. |
normalizedUrl | نشانی وب پس از هر اقدام عادی سازی. این یک URL تجربه کاربری معتبر است که به طور منطقی می توان آن را جستجو کرد. |
محدودیت های نرخ
CrUX API به 150 پرس و جو در دقیقه برای هر پروژه Google Cloud محدود شده است که بدون هزینه ارائه می شود. این محدودیت و استفاده فعلی شما را میتوان در Google Cloud Console مشاهده کرد. این سهمیه سخاوتمندانه باید برای اکثر موارد استفاده کافی باشد و امکان پرداخت برای سهمیه افزایش یافته وجود ندارد.