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 درصد است.

انواع مقادیر متریک

نگاشت نام متریک BigQuery

دوره جمع آوری

از اکتبر 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 روزه از معیارهای جمع‌آوری شده است. این بدان معناست که داده‌های ارائه‌شده در گزارش UX Chrome در هر زمان معین، در واقع داده‌های ۲۸ روز گذشته است که با هم جمع‌شده‌اند.

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

به عنوان مثال، برای درخواست بزرگترین مقادیر رنگ محتوا برای دسکتاپ برای صفحه اصلی اسناد برنامه‌نویس 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 مجموعه‌ای از داده‌های تجمیع تجربه کاربر برای یک معیار عملکرد وب است، مانند اولین رنگ محتوا. ممکن است حاوی یک هیستوگرام خلاصه از استفاده از کروم در دنیای واقعی به‌عنوان مجموعه‌ای از bins ، داده‌های صدک خاص (مانند p75)، یا ممکن است شامل کسرهای برچسب‌گذاری شده باشد.

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

یا

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

بن

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

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

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

صدک ها

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

{
  "P75": value
}

کسری

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
}

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

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