CrUX History API

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

تاریخ انتشار: 7 فوریه 2023، آخرین به روز رسانی: 11 آوریل 2025

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

آن را امتحان کنید!

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

CrUX History API امکان پرس و جو از معیارهای تجربه کاربری تاریخی را برای یک URI خاص مانند "دریافت روندهای UX تاریخی برای مبدا https://example.com " فراهم می کند.

History API از همان ساختار CrUX API روزانه پیروی می کند به جز اینکه مقادیر در یک آرایه داده می شوند و کلیدها با نام های جمع برچسب گذاری می شوند (به عنوان مثال، histogramTimeseries به جای histogram ، یا p75s به جای p75 ).

کلید CrUX API

مانند API روزانه، استفاده از CrUX History API به یک کلید Google Cloud API نیاز دارد که برای استفاده از Chrome UX Report API ارائه شده است. همین کلید را می توان برای 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 نشان می‌دهد که رکورد حاوی اطلاعاتی درباره بارگیری‌هایی است که روی یک دستگاه تلفن همراه انجام شده است.

فاکتور فرم

CrUX History API فقط به صورت انباشته بر اساس ابعاد فاکتور شکل در دسترس است. این یک کلاس کلی از دستگاه است که به PHONE ، TABLET و DESKTOP تقسیم می شود.

متریک

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

هیستوگرام ها

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

یک هیستوگرام سه بن برای یک متریک نمونه به این صورت است:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

این داده ها نشان می دهد که 91.90٪ از بارگذاری های صفحه، مقدار متریک مثال را بین 0ms تا 2500ms برای اولین دوره مجموعه در تاریخ تجربه کرده اند، به دنبال آن 92.03٪، 91.94٪... واحدهای متریک در این هیستوگرام موجود نیستند، در این مورد ما میلی ثانیه را فرض می کنیم.

علاوه بر این، 5.21 درصد از بارگیری‌های صفحه، مقدار متریک نمونه بین 2500 میلی‌ثانیه تا 4000 میلی‌ثانیه را در اولین دوره مجموعه در تاریخچه تجربه کردند، و 2.88 درصد از بارگیری‌های صفحه مقداری بیش از 4000 میلی‌ثانیه را در اولین دوره مجموعه در تاریخ تجربه کردند.

صدک ها

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

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

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

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

کسری

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

مثال:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

در این مثال، جدیدترین نقطه داده نشان می دهد که 14.21 درصد از بارگذاری صفحات از دسکتاپ و 82.88 درصد از تلفن ها بوده است.

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

از آنجایی که CrUX History API از همان انواع مقادیر متریک استفاده می کند، می توانید برای جزئیات بیشتر به اسناد روزانه انواع ارزش متریک CrUX API مراجعه کنید.

واجد شرایط بودن متریک

بر اساس معیارهای واجد شرایط بودن، یک مبدأ یا URL ممکن است فقط برای برخی از دوره‌های مجموعه تحت پوشش API تاریخچه CrUX واجد شرایط باشد. در این موارد، CrUX History API "NaN" را برای چگالی های histogramTimeseries و برای percentilesTimeseries برای دوره های مجموعه ای که داده های واجد شرایط ندارند، null برمی گرداند. دلیل تفاوت این است که تراکم هیستوگرام همیشه اعداد است، در حالی که صدک ها می توانند اعداد یا رشته ها باشند (CLS از رشته ها استفاده می کند، حتی اگر شبیه به اعداد باشند).

به عنوان مثال، اگر دوره دوم هیچ داده واجد شرایطی نداشت، به صورت زیر نشان داده می شود:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

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

دوره های جمع آوری

CrUX History API حاوی یک شی collectionPeriods با آرایه ای از فیلدهای firstDate و endDate است که تاریخ شروع و پایان هر پنجره تجمع را نشان می دهد. به عنوان مثال:

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

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

History API هر دوشنبه به‌روزرسانی می‌شود و حاوی داده‌ها تا شنبه قبل است (طبق تاخیر استاندارد 2 روزه). این شامل داده های 40 هفته ای قبلی است - یک دوره جمع آوری در هفته. به طور پیش فرض، 25 دوره جمع آوری بازگردانده می شود. این را می توان با تنظیم "collectionPeriodCount" در درخواست به عددی بین 1 تا 40 تغییر داد.

از آنجایی که هر دوره جمع آوری حاوی داده های 28 روزه قبلی است و دوره های جمع آوری در هفته است، این بدان معناست که دوره های جمع آوری با هم همپوشانی دارند. آنها مشابه میانگین متحرک داده ها هستند، با داده های سه هفته ای که در هر دوره بعدی گنجانده شده است و یک هفته متفاوت است.

پرس و جوهای نمونه

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

به استفاده از queryHistoryRecord به جای queryRecord API روزانه CrUX توجه کنید.

بدن نمونه این است:

{
  "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:queryHistoryRecord?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 در درخواست مشخص نشده باشد)

اگر مقدار formFactor ارائه نشود، مقادیر در تمام عوامل فرم جمع می شوند.

برای نمونه سوالات بیشتر به استفاده از راهنمای CrUX History API مراجعه کنید.

خط لوله داده

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

میانگین چرخشی

داده‌های گزارش Chrome UX میانگین چرخشی 28 روزه از معیارهای جمع‌آوری شده است. این بدان معناست که داده‌های ارائه‌شده در گزارش UX Chrome در هر زمان معین، در واقع داده‌های ۲۸ روز گذشته است که با هم جمع‌شده‌اند.

History API شامل تعدادی دوره گردآوری است که هر کدام این 28 روز را شامل می شود. از آنجایی که هر دوره جمع آوری حاوی داده های 28 روزه قبلی است و دوره های جمع آوری در هفته است، این بدان معناست که دوره های جمع آوری با هم همپوشانی دارند. آنها مشابه میانگین متحرک داده ها هستند، با داده های سه هفته ای که در هر دوره بعدی گنجانده شده است و یک هفته متفاوت است.

به روز رسانی های هفتگی

History API هر دوشنبه حدود ساعت 04:00 UTC به‌روزرسانی می‌شود و تا شنبه قبل (طبق تاخیر استاندارد 2 روزه) حاوی داده‌ها است. این شامل 40 هفته (تقریباً 10 ماه) داده های قبلی، یک دوره جمع آوری در هفته است. توجه داشته باشید که به‌طور پیش‌فرض، ما 25 ورودی در هر سری زمانی را برمی‌گردانیم. اما این را می توان با تعیین پارامتر درخواست collectionPeriodCount لغو کرد.

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

طرحواره

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

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

درخواست بدن

CrUX History API از بدنه‌های درخواستی مشابه با CrUX API روزانه ، با یک فیلد اضافی و اختیاری "collectionPeriodCount" استفاده می‌کند:

{
  "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.

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

به عنوان مثال، برای درخواست مقادیر Largest Contentful Paint برای صفحه اصلی web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

این درخواست مشابه شامل فیلد collectionPeriodCount اختیاری PeriodCount می‌شود و 40 مدخل سری زمانی ارائه می‌کند که تقریباً 10 ماه سابقه عملکرد وب را برای مبدا https://web.dev ارائه می‌کند:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

بدن پاسخگو

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

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

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

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

کلید

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

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

یا

"fractionTimeseries": {
  object (Fractions)
}

بن

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

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

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

صدک ها

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

{
  "P75": value
}

کسری

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

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

تقریباً مانند مقادیر چگالی در سطل های هیستوگرام، هر fraction یک عدد 0.0 <= value <= 1.0 است و جمع آنها به ~1.0 می رسد. وقتی متریک برای دوره جمع آوری خاصی در دسترس نباشد، ورودی مربوطه در همه آرایه های کسری "NaN" خواهد بود.

UrlNormalization

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

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

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

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

تاریخ انتشار: 7 فوریه 2023، آخرین به روز رسانی: 11 آوریل 2025

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

آن را امتحان کنید!

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

CrUX History API امکان پرس و جو از معیارهای تجربه کاربری تاریخی را برای یک URI خاص مانند "دریافت روندهای UX تاریخی برای مبدا https://example.com " فراهم می کند.

History API از همان ساختار CrUX API روزانه پیروی می کند به جز اینکه مقادیر در یک آرایه داده می شوند و کلیدها با نام های جمع برچسب گذاری می شوند (به عنوان مثال، histogramTimeseries به جای histogram ، یا p75s به جای p75 ).

کلید CrUX API

مانند API روزانه، استفاده از CrUX History API به یک کلید Google Cloud API نیاز دارد که برای استفاده از Chrome UX Report API ارائه شده است. همین کلید را می توان برای 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 نشان می‌دهد که رکورد حاوی اطلاعاتی درباره بارگیری‌هایی است که روی یک دستگاه تلفن همراه انجام شده است.

فاکتور فرم

CrUX History API فقط به صورت انباشته بر اساس ابعاد فاکتور شکل در دسترس است. این یک کلاس کلی از دستگاه است که به PHONE ، TABLET و DESKTOP تقسیم می شود.

متریک

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

هیستوگرام ها

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

یک هیستوگرام سه بن برای یک متریک نمونه به این صورت است:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
}

این داده ها نشان می دهد که 91.90٪ از بارگذاری های صفحه، مقدار متریک مثال را بین 0ms تا 2500ms برای اولین دوره مجموعه در تاریخ تجربه کرده اند، به دنبال آن 92.03٪، 91.94٪... واحدهای متریک در این هیستوگرام موجود نیستند، در این مورد ما میلی ثانیه را فرض می کنیم.

علاوه بر این، 5.21 درصد از بارگیری‌های صفحه، مقدار متریک نمونه بین 2500 میلی‌ثانیه تا 4000 میلی‌ثانیه را در اولین دوره مجموعه در تاریخچه تجربه کردند، و 2.88 درصد از بارگیری‌های صفحه مقداری بیش از 4000 میلی‌ثانیه را در اولین دوره مجموعه در تاریخ تجربه کردند.

صدک ها

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

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

{
  "percentilesTimeseries": {
    "p75s": [1362, 1352, 1344, 1356, 1366, 1377]
  },
}

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

کسری

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

مثال:

{    
  "fractionTimeseries": {
    "desktop": {"fractions": [0.3195, 0.2115, 0.1421]},
    "phone": {"fractions": [0.6295, 0.7544, 0.8288]},
    "tablet": {"fractions": [0.051, 0.0341, 0.029]}
  }
}

در این مثال، جدیدترین نقطه داده نشان می دهد که 14.21 درصد از بارگذاری صفحات از دسکتاپ و 82.88 درصد از تلفن ها بوده است.

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

از آنجایی که CrUX History API از همان انواع مقادیر متریک استفاده می کند، می توانید برای جزئیات بیشتر به اسناد روزانه انواع ارزش متریک CrUX API مراجعه کنید.

واجد شرایط بودن متریک

بر اساس معیارهای واجد شرایط بودن، یک مبدأ یا URL ممکن است فقط برای برخی از دوره‌های مجموعه تحت پوشش API تاریخچه CrUX واجد شرایط باشد. در این موارد، CrUX History API "NaN" را برای چگالی های histogramTimeseries و برای percentilesTimeseries برای دوره های مجموعه ای که داده های واجد شرایط ندارند، null برمی گرداند. دلیل تفاوت این است که تراکم هیستوگرام همیشه اعداد است، در حالی که صدک ها می توانند اعداد یا رشته ها باشند (CLS از رشته ها استفاده می کند، حتی اگر شبیه به اعداد باشند).

به عنوان مثال، اگر دوره دوم هیچ داده واجد شرایطی نداشت، به صورت زیر نشان داده می شود:

{
  "histogramTimeseries": [
    {
      "start": 0,
      "end": 2500,
      "densities": [0.9190, "NaN", 0.9194, 0.9195, 0.9183, 0.9187]
    },
    {
      "start": 2500,
      "end": 4000,
      "densities": [0.0521, "NaN", 0.0518, 0.0518, 0.0526, 0.0527]
    },
    {
      "start": 4000,
      "densities": [0.0288, "NaN", 0.0286, 0.0285, 0.0290, 0.0285]
    }
  ],
  "percentilesTimeseries": {
    "p75s": [1362, null, 1344, 1356, 1366, 1377]
  },
}

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

دوره های جمع آوری

CrUX History API حاوی یک شی collectionPeriods با آرایه ای از فیلدهای firstDate و endDate است که تاریخ شروع و پایان هر پنجره تجمع را نشان می دهد. به عنوان مثال:

    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]

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

History API هر دوشنبه به‌روزرسانی می‌شود و حاوی داده‌ها تا شنبه قبل است (طبق تاخیر استاندارد 2 روزه). این شامل داده های 40 هفته ای قبلی است - یک دوره جمع آوری در هفته. به طور پیش فرض، 25 دوره جمع آوری بازگردانده می شود. این را می توان با تنظیم "collectionPeriodCount" در درخواست به عددی بین 1 تا 40 تغییر داد.

از آنجایی که هر دوره جمع آوری حاوی داده های 28 روزه قبلی است و دوره های جمع آوری در هفته است، این بدان معناست که دوره های جمع آوری با هم همپوشانی دارند. آنها مشابه میانگین متحرک داده ها هستند، با داده های سه هفته ای که در هر دوره بعدی گنجانده شده است و یک هفته متفاوت است.

پرس و جوهای نمونه

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

به استفاده از queryHistoryRecord به جای queryRecord API روزانه CrUX توجه کنید.

بدن نمونه این است:

{
  "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:queryHistoryRecord?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 در درخواست مشخص نشده باشد)

اگر مقدار formFactor ارائه نشود، مقادیر در تمام عوامل فرم جمع می شوند.

برای نمونه سوالات بیشتر به استفاده از راهنمای CrUX History API مراجعه کنید.

خط لوله داده

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

میانگین چرخشی

داده‌های گزارش Chrome UX میانگین چرخشی 28 روزه از معیارهای جمع‌آوری شده است. این بدان معناست که داده‌های ارائه‌شده در گزارش UX Chrome در هر زمان معین، در واقع داده‌های ۲۸ روز گذشته است که با هم جمع‌شده‌اند.

History API شامل تعدادی دوره گردآوری است که هر کدام این 28 روز را شامل می شود. از آنجایی که هر دوره جمع آوری حاوی داده های 28 روزه قبلی است و دوره های جمع آوری در هفته است، این بدان معناست که دوره های جمع آوری با هم همپوشانی دارند. آنها مشابه میانگین متحرک داده ها هستند، با داده های سه هفته ای که در هر دوره بعدی گنجانده شده است و یک هفته متفاوت است.

به روز رسانی های هفتگی

History API هر دوشنبه حدود ساعت 04:00 UTC به‌روزرسانی می‌شود و تا شنبه قبل (طبق تاخیر استاندارد 2 روزه) حاوی داده‌ها است. این شامل 40 هفته (تقریباً 10 ماه) داده های قبلی، یک دوره جمع آوری در هفته است. توجه داشته باشید که به‌طور پیش‌فرض، ما 25 ورودی در هر سری زمانی را برمی‌گردانیم. اما این را می توان با تعیین پارامتر درخواست collectionPeriodCount لغو کرد.

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

طرحواره

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

درخواست HTTP

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

URL از دستور GRPC Transcoding استفاده می کند.

درخواست بدن

CrUX History API از بدنه‌های درخواستی مشابه با CrUX API روزانه ، با یک فیلد اضافی و اختیاری "collectionPeriodCount" استفاده می‌کند:

{
  "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.

  "collectionPeriodCount": int32 // Optional: Number of periods to collect
}

به عنوان مثال، برای درخواست مقادیر Largest Contentful Paint برای صفحه اصلی web.dev:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

این درخواست مشابه شامل فیلد collectionPeriodCount اختیاری PeriodCount می‌شود و 40 مدخل سری زمانی ارائه می‌کند که تقریباً 10 ماه سابقه عملکرد وب را برای مبدا https://web.dev ارائه می‌کند:

{
  "url": "https://web.dev/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ],
  "collectionPeriodCount": 40
}

بدن پاسخگو

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

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

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

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187, ...
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527, ...
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285, ...
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377, ...
          ]
        }
      }
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }, {
        ...
      }
    ]
  }
}

کلید

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

{
  "histogramTimeseries": [
    {
      object (Bin)
    }
  ],
  "percentilesTimeseries": {
    object (Percentiles)
  }
}

یا

"fractionTimeseries": {
  object (Fractions)
}

بن

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

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

{
  "start": value,
  "end": value,
  "densities": [number, number, number...etc.]
}

صدک ها

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

{
  "P75": value
}

کسری

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

{
  "label_1": { "fractions": array[fraction]},
  "label_1": { "fractions": array[fraction]},
  ...
  "label_n": { "fractions": array[fraction]}
}

تقریباً مانند مقادیر چگالی در سطل های هیستوگرام ، هر fraction عدد 0.0 <= value <= 1.0 است و آنها تا 1.0 پوند اضافه می کنند. هنگامی که این متریک برای یک دوره جمع آوری خاص در دسترس نباشد ، ورودی مربوطه در کلیه آرایه های کسری "نان" خواهد بود.

urlnormalization

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

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

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

API CRUX HISTORY همان حد را با CRUX API برای 150 نمایش داده در هر دقیقه در هر پروژه Google Cloud برای هر یک از API ، که بدون شارژ ارائه می شود ، به اشتراک می گذارد. این حد و استفاده فعلی شما را می توان در کنسول Google Cloud مشاهده کرد. این سهمیه سخاوتمندانه باید برای اکثریت قریب به اتفاق موارد استفاده کافی باشد و پرداخت هزینه های افزایش یافته امکان پذیر نیست.