API CrUX cấp quyền truy cập độ trễ thấp vào dữ liệu trải nghiệm người dùng thực được tổng hợp tại trang và nguồn gốc.
Trường hợp sử dụng phổ biến
API CrUX cho phép truy vấn chỉ số trải nghiệm người dùng cho một URI cụ thể, chẳng hạn như "Lấy chỉ số cho nguồn gốc https://example.com
".
Khoá API CrUX
Để sử dụng API CrUX, bạn phải có khoá API của Google Cloud. Bạn có thể tạo một mã trong trang Thông tin xác thực và cung cấp thông tin đó để sử dụng Chrome UX Report API
.
Sau khi bạn có khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=[YOUR_API_KEY]
vào tất cả URL yêu cầu. Xem Truy vấn mẫu.
Khoá API an toàn để nhúng trong URL; không cần phương thức mã hoá.
Mô hình dữ liệu
Phần này trình bày chi tiết cấu trúc của dữ liệu trong các yêu cầu và phản hồi.
Ghi âm
Một phần thông tin riêng biệt về một trang hoặc trang web. Một bản ghi có thể chứa dữ liệu dành riêng cho một giá trị nhận dạng và cho một tổ hợp phương diện cụ thể. Một bản ghi có thể chứa dữ liệu về một hoặc nhiều chỉ số.
Giá trị nhận dạng
Giá trị nhận dạng chỉ định những bản ghi cần được tra cứu. Trong CrUX, các giá trị nhận dạng này là các trang web.
Điểm gốc
Khi giá trị nhận dạng là một nguồn gốc, thì tất cả dữ liệu có trên tất cả các trang thuộc nguồn gốc đó sẽ được tổng hợp lại với nhau. Ví dụ: giả sử nguồn gốc http://www.example.com
có các trang được trình bày theo sơ đồ trang web này:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Điều này có nghĩa là khi truy vấn Báo cáo trải nghiệm người dùng trên Chrome có nguồn gốc được đặt thành http://www.example.com
, dữ liệu cho http://www.example.com/
, http://www.example.com/foo.html
và http://www.example.com/bar.html
sẽ được trả về, tổng hợp lại với nhau, vì đó đều là các trang thuộc nguồn gốc đó.
URL
Khi giá trị nhận dạng là một URL, thì hệ thống chỉ trả về dữ liệu cho URL cụ thể đó. Xem lại sơ đồ trang web gốc http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Nếu giá trị nhận dạng được đặt thành URL có giá trị http://www.example.com/foo.html
, thì chỉ dữ liệu cho trang đó được trả về.
Kích thước
Phương diện xác định một nhóm dữ liệu cụ thể mà một bản ghi đang được tổng hợp, ví dụ: hệ số hình dạng PHONE
cho biết rằng bản ghi đó chứa thông tin về các lượt tải diễn ra trên thiết bị di động. Mỗi phương diện sẽ có một số lượng giá trị nhất định và ngầm nêu rõ việc không chỉ định phương diện đó có nghĩa là phương diện này được tổng hợp trên tất cả các giá trị. Ví dụ: việc chỉ định không có hệ số hình dạng nào cho biết bản ghi có chứa thông tin về các lượt tải diễn ra trên bất kỳ hệ số hình dạng nào.
Kiểu dáng
Lớp thiết bị mà người dùng cuối đã sử dụng để điều hướng đến trang. Đây là một lớp chung của thiết bị được chia thành PHONE
, TABLET
và DESKTOP
.
Loại kết nối hiệu quả
Loại kết nối hiệu quả là chất lượng kết nối ước tính của thiết bị khi điều hướng đến trang. Đây là một lớp chung được chia thành offline
, slow-2G
, 2G
, 3G
và 4G
.
Chỉ số
Chúng tôi báo cáo các chỉ số dưới dạng tổng hợp thống kê dưới dạng biểu đồ, phân vị và phân số.
Các giá trị dấu phẩy động được làm tròn đến 4 chữ số thập phân (lưu ý rằng chỉ số cumulative_layout_shift
được mã hoá kép dưới dạng chuỗi, vì vậy, không được xem là số thực và được báo cáo đến 2 chữ số thập phân trong chuỗi).
Biểu đồ
Khi các chỉ số được biểu thị bằng biểu đồ, chúng tôi sẽ cho bạn thấy tỷ lệ phần trăm tải trang thuộc phạm vi cụ thể của chỉ số đó.
Biểu đồ ba thùng đơn giản cho một chỉ số mẫu sẽ có dạng như sau:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Dữ liệu này cho thấy rằng đối với 38, 18% lượt tải trang,chỉ số ví dụ được đo trong khoảng từ 0 mili giây đến 1.000 mili giây. Các đơn vị của chỉ số không có trong biểu đồ này, trong trường hợp này, chúng tôi sẽ giả định là mili giây.
Ngoài ra, 49,91% lượt tải trang có giá trị chỉ số từ 1.000 mili giây đến 3.000 mili giây, và 11,92% có giá trị lớn hơn 3.000 mili giây.
Phân vị
Chỉ số cũng có thể chứa các phân vị có thể hữu ích cho việc phân tích thêm. Chúng tôi báo cáo các giá trị chỉ số cụ thể tại phân vị đã cho cho chỉ số đó. Các mô-đun này dựa trên tập hợp đầy đủ dữ liệu có sẵn chứ không phải dữ liệu liên kết cuối cùng, vì vậy, chúng không nhất thiết phải khớp với phân vị nội suy dựa trên biểu đồ liên kết cuối cùng.
{
"percentiles": {
"p75": 2063
}
}
Trong ví dụ này, ít nhất 75% lượt tải trang được đo lường bằng giá trị chỉ số <= 2063
.
Phân số
Phân số cho biết tỷ lệ phần trăm tải trang có thể được gắn nhãn theo một cách cụ thể. Trong trường hợp này, giá trị chỉ số là các nhãn này.
Ví dụ: chỉ số form_factors
bao gồm đối tượng fractions
liệt kê bảng chi tiết về hệ số hình dạng (hoặc thiết bị) mà truy vấn đã cho đề cập:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
Trong trường hợp này, 3,77% tải trang được đo trên máy tính để bàn, 2,88% trên máy tính bảng và 93,35% trên điện thoại, cho kết quả tổng cộng 100%.
Các loại giá trị chỉ số
Tên chỉ số API CrUX | Loại dữ liệu | Đơn vị hệ mét | Phương pháp tổng hợp thống kê | Tài liệu |
---|---|---|---|---|
cumulative_layout_shift |
2 chữ số thập phân kép được mã hoá dưới dạng chuỗi | không có đơn vị | biểu đồ có 3 thùng, phân vị có p75 | cls |
first_contentful_paint |
int | mili giây | biểu đồ có 3 thùng, phân vị có p75 | fcp |
first_input_delay (không dùng nữa) |
int | mili giây | biểu đồ có 3 thùng, phân vị có p75 | chính thức |
interaction_to_next_paint |
int | mili giây | biểu đồ có 3 thùng, phân vị có p75 | inp |
largest_contentful_paint |
int | mili giây | biểu đồ có 3 thùng, phân vị có p75 | lcp |
experimental_time_to_first_byte |
int | mili giây | biểu đồ có 3 thùng, phân vị có p75 | ttfb |
form_factors |
Dấu thập phân đôi có 4 chữ số | phần trăm | ánh xạ từ kiểu dáng đến phân số | hệ số hình dạng |
navigation_types |
Dấu thập phân đôi có 4 chữ số | phần trăm | ánh xạ từ kiểu điều hướng đến phân số | các loại điều hướng |
Liên kết tên chỉ số BigQuery
Tên chỉ số API CrUX | Tên chỉ số BigQuery |
---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
first_input_delay |
first_input.delay |
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 |
không áp dụng |
Kỳ hạn thu thập
Kể từ tháng 10 năm 2022, API CrUX chứa đối tượng collectionPeriod
với các trường firstDate
và endDate
tượng trưng cho ngày bắt đầu và ngày kết thúc của khoảng thời gian tổng hợp. Ví dụ:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Nhờ đó, bạn có thể hiểu rõ hơn về dữ liệu và liệu dữ liệu đó đã được cập nhật cho ngày hôm đó hay đang trả về cùng một dữ liệu như hôm qua.
Xin lưu ý rằng API CrUX sẽ trễ hơn khoảng 2 ngày so với ngày hôm nay vì API CrUX đang chờ dữ liệu hoàn chỉnh trong ngày và cần một khoảng thời gian xử lý trước khi có thể cung cấp trong API. Múi giờ được sử dụng là Giờ chuẩn Thái Bình Dương (PST) và không thay đổi theo giờ mùa hè.
Cụm từ tìm kiếm ví dụ
Các truy vấn được gửi dưới dạng đối tượng JSON bằng cách sử dụng yêu cầu POST tới https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
với dữ liệu truy vấn dưới dạng đối tượng JSON trong nội dung POST:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Ví dụ: bạn có thể gọi lệnh này từ curl
bằng dòng lệnh sau (thay thế API_KEY
bằng khoá của bạn):
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"]}'
Bạn có thể xem dữ liệu cấp trang thông qua API bằng cách chuyển thuộc tính url
trong truy vấn thay vì origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Nếu bạn không đặt thuộc tính metrics
, thì hệ thống sẽ trả về mọi chỉ số có sẵn:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(không dùng nữa)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(chỉ được báo cáo nếu không cóformFactor
nào được chỉ định trong yêu cầu)
Nếu bạn không cung cấp giá trị formFactor
, thì các giá trị này sẽ được tổng hợp trên tất cả các hệ số hình dạng.
Hãy xem bài viết Sử dụng API Báo cáo trải nghiệm người dùng trên Chrome để biết thêm các truy vấn mẫu.
Quy trình dữ liệu
Tập dữ liệu CrUX được xử lý theo một quy trình để hợp nhất, tổng hợp và lọc dữ liệu trước khi sử dụng API.
Trung bình luân phiên
Dữ liệu trong Báo cáo trải nghiệm người dùng trên Chrome là số liệu trung bình luân phiên trong 28 ngày của các chỉ số tổng hợp. Điều này có nghĩa là dữ liệu được trình bày trong Báo cáo trải nghiệm người dùng trên Chrome tại một thời điểm bất kỳ sẽ thực sự là dữ liệu trong 28 ngày qua được tổng hợp lại với nhau.
Điều này tương tự như cách tập dữ liệu CrUX trên BigQuery tổng hợp báo cáo hằng tháng.
Tin cập nhật hằng ngày
Dữ liệu được cập nhật hằng ngày vào khoảng 04:00 (giờ UTC). Không có thoả thuận mức độ dịch vụ nào cho thời gian cập nhật; yêu cầu này được chạy trên cơ sở nỗ lực tối đa mỗi ngày.
Lược đồ
Có một điểm cuối duy nhất cho API CrUX chấp nhận các yêu cầu HTTP POST
. API trả về một record
chứa một hoặc nhiều metrics
tương ứng với dữ liệu hiệu suất về trang gốc hoặc trang được yêu cầu.
Yêu cầu HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
URL sử dụng cú pháp Chuyển mã gRPC.
Nội dung yêu cầu
Nội dung yêu cầu phải chứa dữ liệu có cấu trúc sau:
{
"effectiveConnectionType": string,
"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.
}
Trường | |
---|---|
effectiveConnectionType |
Loại kết nối hiệu quả là một tham số truy vấn chỉ định lớp mạng hiệu quả chứa dữ liệu của bản ghi. Trường này sử dụng các giá trị Lưu ý: Nếu không có loại kết nối hiệu quả nào được chỉ định, thì một bản ghi đặc biệt với dữ liệu tổng hợp về tất cả các loại kết nối hiệu quả sẽ được trả về. |
formFactor |
Hệ số hình dạng là một phương diện truy vấn chỉ định loại thiết bị chứa dữ liệu của bản ghi. Trường này sử dụng các giá trị Lưu ý: Nếu bạn không chỉ định hệ số hình dạng nào, thì hệ thống sẽ trả về một bản ghi đặc biệt chứa dữ liệu tổng hợp trên tất cả hệ số hình dạng. |
metrics[] |
Các chỉ số cần đưa vào phản hồi. Nếu bạn không chỉ định thì mọi chỉ số tìm thấy sẽ được trả về. Giá trị được phép: |
Trường hợp url_ . url_pattern là giá trị nhận dạng chính của hoạt động tra cứu bản ghi. Đó chỉ có thể là một trong những trường hợp sau: |
|
origin |
"Nguồn gốc" Ví dụ: |
url |
Ví dụ: |
Ví dụ: để yêu cầu giá trị hiển thị nội dung lớn nhất trên máy tính cho trang chủ tài liệu dành cho nhà phát triển Chrome:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Nội dung phản hồi
Các yêu cầu thành công sẽ trả về phản hồi bằng đối tượng record
và urlNormalizationDetails
theo cấu trúc sau:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Ví dụ: phản hồi cho nội dung yêu cầu trong yêu cầu trước đó có thể là:
{
"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
}
}
}
}
Khoá
Key
xác định tất cả các phương diện xác định bản ghi này là duy nhất.
{
"effectiveConnectionType": string,
"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.
}
Trường | |
---|---|
formFactor |
Hệ số hình dạng là lớp thiết bị mà tất cả người dùng đã dùng để truy cập vào trang web cho bản ghi này. Nếu bạn chưa chỉ định hệ số hình dạng thì dữ liệu tổng hợp trên tất cả hệ số hình dạng sẽ được trả về. |
effectiveConnectionType |
Loại kết nối hiệu quả là lớp kết nối chung mà tất cả người dùng gặp phải đối với bản ghi này. Trường này sử dụng các giá trị ["Offline", "slow-2G", "2G", "3G", "4G"] như được nêu trong: https://wicg.github.io/netinfo/#effective-connection-types Nếu bạn chưa chỉ định loại kết nối hiệu quả thì dữ liệu tổng hợp về mọi loại kết nối hiệu quả sẽ được trả về. |
Trường hợp url_ . Mẫu URL là URL áp dụng bản ghi. url_ chỉ có thể là một trong những trạng thái sau: |
|
origin |
Lưu ý: Khi bạn chỉ định một |
url |
Lưu ý: Khi bạn chỉ định |
Chỉ số
metric
là tập hợp dữ liệu tổng hợp về trải nghiệm người dùng cho một chỉ số hiệu suất web duy nhất, chẳng hạn như hiển thị nội dung đầu tiên.
Tệp này có thể chứa biểu đồ tóm tắt mức sử dụng Chrome thực tế dưới dạng một chuỗi bins
, dữ liệu phân vị cụ thể
(chẳng hạn như p75) hoặc có thể chứa các phân số được gắn nhãn.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
hoặc
{
"fractions": {
object (Fractions)
}
}
Trường | |
---|---|
histogram[] |
Biểu đồ trải nghiệm người dùng cho một chỉ số. Biểu đồ sẽ có ít nhất một thùng rác và mật độ của tất cả các thùng sẽ cộng lại là ~1. |
percentiles |
Các phân vị hữu ích phổ biến của Chỉ số. Loại giá trị cho phân vị sẽ giống với loại giá trị được cung cấp cho Thùng biểu đồ. |
fractions |
Đối tượng này chứa các phân số được gắn nhãn có tổng bằng ~1. Các phân số được làm tròn đến 4 chữ số thập phân. |
Khoảng giá trị
bin
là một phần dữ liệu riêng biệt kéo dài từ đầu đến cuối hoặc nếu không có điểm kết thúc nào được cung cấp từ đầu đến vô cực dương.
Giá trị bắt đầu và kết thúc của thùng được cung cấp theo loại giá trị của số liệu mà nó biểu thị. Ví dụ: nội dung đầu tiên được đo bằng mili giây và hiển thị dưới dạng số nguyên, do đó, các thùng chỉ số của nó sẽ sử dụng int32 cho loại bắt đầu và kết thúc. Tuy nhiên, mức thay đổi bố cục tích luỹ được tính bằng số thập phân không đơn vị và biểu thị dưới dạng số thập phân được mã hoá dưới dạng chuỗi, do đó, các thùng chỉ số sẽ sử dụng chuỗi cho loại giá trị của biến này.
{
"start": value,
"end": value,
"density": number
}
Trường | |
---|---|
start |
Bắt đầu là điểm bắt đầu của thùng dữ liệu. |
end |
Điểm kết thúc là điểm kết thúc của thùng dữ liệu. Nếu kết thúc không được điền, thì khoảng giá trị không có kết thúc và hợp lệ từ bắt đầu đến +inf. |
density |
Tỷ lệ người dùng đã thấy giá trị của thùng này cho chỉ số đã cho. Mật độ được làm tròn đến 4 chữ số thập phân. |
Phân vị
Percentiles
chứa giá trị tổng hợp của một chỉ số tại một phân vị thống kê nhất định. Những chỉ số này được dùng để ước tính giá trị của một chỉ số theo trải nghiệm của một tỷ lệ phần trăm người dùng trên tổng số người dùng.
{
"P75": value
}
Trường | |
---|---|
p75 |
75% lượt tải trang có chỉ số cụ thể bằng hoặc thấp hơn giá trị này. |
Phân số
Fractions
chứa các phân số có nhãn tổng cộng tối đa là ~1. Mỗi nhãn mô tả một lượt tải trang theo một cách nào đó, vì vậy, các chỉ số được biểu thị theo cách này có thể được coi là tạo ra các giá trị riêng biệt thay vì các giá trị số, và các phân số thể hiện tần suất đo lường một giá trị riêng biệt cụ thể.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Giống như các giá trị mật độ trong thùng biểu đồ, mỗi fraction
là một số 0.0 <= value <= 1.0
và có tổng là ~1.
UrlNormalization
Đối tượng biểu thị các hành động chuẩn hoá được thực hiện để chuẩn hoá URL nhằm tăng khả năng tra cứu thành công. Đây là những thay đổi tự động đơn giản được thực hiện khi tra cứu url_pattern
được cung cấp sẽ được biết là không thành công. Các thao tác phức tạp như sau các lệnh chuyển hướng sẽ không được xử lý.
{
"originalUrl": string,
"normalizedUrl": string
}
Trường | |
---|---|
originalUrl |
URL được yêu cầu ban đầu trước khi thực hiện các hành động chuẩn hoá. |
normalizedUrl |
URL sau mọi thao tác chuẩn hoá. Đây là một URL hợp lệ liên quan đến trải nghiệm người dùng, có thể tra cứu được một cách hợp lý. |
Giới hạn số lượng yêu cầu
API CrUX chỉ được cung cấp miễn phí ở mức 150 truy vấn mỗi phút cho mỗi dự án trên Google Cloud. Bạn có thể xem hạn mức này và mức sử dụng hiện tại của mình trong Google Cloud Console. Hạn mức khổng lồ này là đủ cho phần lớn các trường hợp sử dụng và bạn không thể phải trả tiền để tăng hạn mức.