CrUX API

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

enum ( FormFactor )

فاکتور فرم یک بعد پرس و جو است که کلاس دستگاهی را که داده های رکورد باید به آن تعلق داشته باشد را مشخص می کند.

این فیلد از مقادیر DESKTOP ، PHONE یا TABLET استفاده می کند.

توجه: اگر هیچ فاکتور فرمی مشخص نشده باشد، یک رکورد ویژه با داده های انباشته روی تمام فاکتورهای فرم برگردانده می شود.

metrics[]

string

معیارهایی که باید در پاسخ گنجانده شود. اگر هیچ یک مشخص نشده باشد، هر معیاری که پیدا شده است برگردانده می شود.

مقادیر مجاز: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]

url_ pattern فیلد اتحادیه. url_pattern شناسه اصلی برای جستجوی رکورد است. می تواند تنها یکی از موارد زیر باشد:
origin

string

url_pattern "origin" به یک الگوی URL که مبدا یک وب سایت است اشاره دارد.

مثال‌ها: "https://example.com" ، "https://cloud.google.com"

url

string

url url_pattern به یک الگوی URL اشاره دارد که هر URL دلخواه است.

مثال‌ها: "https://example.com/ ، https://cloud.google.com/why-google-cloud/"

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

enum ( FormFactor )

فرم فاکتور کلاس دستگاهی است که همه کاربران برای دسترسی به سایت برای این رکورد از آن استفاده کردند.

اگر فاکتور فرم نامشخص باشد، داده های انباشته شده روی همه فاکتورهای فرم بازگردانده می شود.

url_ pattern فیلد اتحادیه. الگوی URL آدرسی است که رکورد روی آن اعمال می شود. url_ pattern می تواند تنها یکی از موارد زیر باشد:
origin

string

origin مبدأ را مشخص می کند که این رکورد برای آن است.

توجه: هنگام تعیین origin ، داده‌های بارگیری‌های تحت این مبدا در تمام صفحات در داده‌های تجربه کاربر سطح مبدا جمع می‌شوند.

url

string

url یک URL خاص را مشخص می کند که این رکورد برای آن است.

توجه: هنگام تعیین یک url ، فقط داده‌های آن URL خاص جمع می‌شوند.

معیارها

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

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

یا

{
  "fractions": {
    object (Fractions)
  }
}
فیلدها
histogram[]

object ( Bin )

هیستوگرام تجربیات کاربر برای یک متریک. هیستوگرام حداقل یک سطل خواهد داشت و چگالی همه سطل ها برابر با 1 می شود.

percentiles

object ( Percentiles )

صدک های مفید رایج متریک. نوع مقدار برای صدک ها مانند انواع مقادیر داده شده برای bin های هیستوگرام خواهد بود.

fractions

object ( Fractions )

این شی شامل کسرهای برچسب‌گذاری شده است که مجموع آنها 1~ می‌شود.

کسرها به 4 رقم اعشار گرد می شوند.

بن

bin یک بخش مجزا از داده است که از ابتدا تا انتها را شامل می شود، یا اگر پایانی از ابتدا تا بی نهایت مثبت داده نشود.

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

{
  "start": value,
  "end": value,
  "density": number
}
فیلدها
start

(integer | string)

Start ابتدای سطل داده است.

end

(integer | string)

End انتهای سطل داده است. اگر end پر نشده باشد، بن پایانی ندارد و از ابتدا تا +inf معتبر است.

density

number

نسبت کاربرانی که مقدار این سطل را برای معیار داده شده تجربه کردند.

تراکم ها به 4 رقم اعشار گرد می شوند.

صدک ها

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

{
  "P75": value
}
فیلدها
p75

(integer | string)

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

string

URL اصلی درخواست شده قبل از هر اقدام عادی سازی.

normalizedUrl

string

نشانی وب پس از هر اقدام عادی سازی. این یک URL تجربه کاربری معتبر است که به طور منطقی می توان آن را جستجو کرد.

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

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