API CrUX Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

API CrUX cung cấp quyền truy cập có độ trễ thấp vào dữ liệu tổng hợp về trải nghiệm người dùng thực tế ở mức độ chi tiết về trang và nguồn gốc.

Hãy làm thử!

Trường hợp sử dụng phổ biến

CrUX API cho phép truy vấn các chỉ số về trải nghiệm người dùng cho một URI cụ thể như "Lấy chỉ số cho nguồn gốc https://example.com".

Khoá API CrUX

Để sử dụng API CrUX, bạn cần có khoá API Google Cloud được cấp để sử dụng Chrome UX Report API.

Lấy và sử dụng khoá API

Mua khoá

Hoặc tạo một mã trong trang Thông tin xác thực.

Sau khi bạn có khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=yourAPIKey vào tất cả URL yêu cầu.

Khoá API an toàn để nhúng vào URL; không cần mã hoá.

Xem Truy vấn mẫu.

Mô hình dữ liệu

Phần này trình bày chi tiết cấu trúc 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ể có 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 cho 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 tra cứu. Trong CrUX, các giá trị nhận dạng này là trang web và trang web.

Điểm gốc

Khi giá trị nhận dạng là một nguồn gốc, tất cả dữ liệu hiện có cho tất cả các trang trong nguồn gốc đó sẽ được tổng hợp với nhau. Ví dụ: giả sử nguồn gốc http://www.example.com có các trang như được nêu trong 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 với 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 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, hệ thống sẽ 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ị là http://www.example.com/foo.html, thì hệ thống sẽ chỉ trả về dữ liệu cho trang đó.

Kích thước

Phương diện xác định một nhóm dữ liệu cụ thể mà bản ghi đang được tổng hợp, ví dụ: hệ số hình dạng PHONE cho biết 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ố giá trị nhất định và việc không chỉ định phương diện đó ngầm ẩn ý rằng phương diện đó được tổng hợp trên tất cả các giá trị. Ví dụ: việc không chỉ định kiểu dáng thiết bị 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 bất kỳ kiểu dáng thiết bị nào.

Kiểu dáng

Lớp thiết bị mà người dùng cuối đã sử dụng để chuyển đến trang. Đây là một lớp thiết bị chung được chia thành PHONE, TABLET và DESKTOP.

Chỉ số

Chúng tôi báo cáo các chỉ số dưới dạng dữ liệu tổng hợp thống kê, trong biểu đồ, phần trăm 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 các chỉ số cumulative_layout_shift là số thực kép được mã hoá dưới dạng chuỗi, vì vậy không được coi 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 thể hiện trong biểu đồ dạng thanh, chúng tôi sẽ cho biết tỷ lệ phần trăm số lượt tải trang thuộc các phạm vi cụ thể cho chỉ số đó.

Biểu đồ thanh ba ngăn cho một chỉ số mẫu 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 biết rằng đối với 38, 18% số lượt tải trang,chỉ số mẫu được đo 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 ta sẽ giả định là mili giây.

Ngoài ra, 49,91% số 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ị nhất định cho chỉ số đó. Các giá trị 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 được phân thành nhóm cuối cùng, vì vậy, các giá trị này không nhất thiết phải khớp với một phần trăm nội suy dựa trên biểu đồ thanh xếp hạng được phân thành nhóm cuối cùng.

{ "percentiles": { "p75": 2063 } }

Trong ví dụ này, ít nhất 75% số lượt tải trang được đo lường bằng giá trị chỉ số <= 2063.

Lưu ý: Các giá trị cho mỗi phân vị được lấy từ dữ liệu tổng hợp, không có nghĩa là có người dùng nào đó thực sự trải nghiệm giá trị được chỉ định, mà chỉ có một tỷ lệ phần trăm số lượt tải trang trải nghiệm giá trị chỉ số thấp hơn giá trị được đưa ra.

Phân số

Phân số cho biết tỷ lệ phần trăm số lượt 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 một đối tượng fractions liệt kê thông tin chi tiết về các hệ số hình dạng (hoặc thiết bị) mà truy vấn nhất định bao gồm:

"form_factors": { "fractions": { "desktop": 0.0377, "tablet": 0.0288, "phone": 0.9335 } }

Trong trường hợp này, 3,77% số lượt tải trang được đo lường trên máy tính, 2,88% trên máy tính bảng và 93,35% trên điện thoại, tổng cộng là 100%.

Loại giá trị chỉ số

Tên chỉ số API CrUX Loại dữ liệu Đơn vị đo lường theo hệ mét Tổng hợp thống kê Tài liệu cumulative_layout_shift 2 chữ số thập phân được mã hoá kép dưới dạng chuỗi không có đơn vị biểu đồ có 3 vùng chứa, các phân vị có p75 cls first_contentful_paint int mili giây biểu đồ có 3 vùng chứa, các phân vị có p75 fcp interaction_to_next_paint int mili giây biểu đồ có 3 vùng chứa, các phân vị có p75 inp largest_contentful_paint int mili giây biểu đồ có 3 vùng chứa, các phân vị có p75 lcp experimental_time_to_first_byte int mili giây biểu đồ có 3 vùng chứa, các phân vị có p75 ttfb form_factors Số thực có 4 chữ số thập phân dấu phần trăm ánh xạ từ hệ số hình dạng đến phân số hệ số hình dạng navigation_types Số thực có 4 chữ số thập phân dấu phần trăm ánh xạ từ loại điều hướng đến phân số các loại điều hướng round_trip_time int mili giây phân vị với p75 rtt

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 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 round_trip_time không áp dụng Lưu ý: Trong BigQuery CrUX, mật độ biểu đồ sẽ cộng lại thành 100% trên mỗi nguồn gốc trên các hệ số hình dạng, vì vậy, chỉ số form_factors mà chúng tôi hỗ trợ trong API được biểu thị dưới dạng mật độ biểu đồ cho first_contentful_paint.

Khoảng thời gian thu thập

Kể từ tháng 10 năm 2022, API CrUX chứa một đối tượng collectionPeriod có các trường firstDate và endDate đại diện 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 } }

Điều này giúp bạn hiểu rõ hơn về dữ liệu và liệu dữ liệu đó đã được cập nhật cho ngày đó hay đang trả về dữ liệu giống như ngày hôm qua.

Lưu ý: API CrUX chậm hơn ngày hôm nay khoảng 2 ngày vì API này chờ dữ liệu hoàn chỉnh trong ngày và cần có một khoảng thời gian xử lý trước khi dữ liệu có trong API. Múi giờ được sử dụng là Giờ chuẩn Thái Bình Dương (PST) và không có thay đổi nào đối với giờ mùa hè.

Bạn cũng có thể xem khoảng thời gian thu thập dữ liệu trong PageSpeed Insights:

Ngoài ra, collectionPeriod sẽ luôn hiển thị 28 ngày, ngay cả khi dữ liệu không phải là dữ liệu của 28 ngày đầy đủ (ví dụ: nếu một trang được ra mắt chưa đầy 28 ngày). collectionPeriod là khoảng thời gian mà dữ liệu CrUX được tổng hợp, không nhất thiết là khoảng thời gian mà dữ liệu thể hiện.

Cụm từ tìm kiếm mẫu

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 đến 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 phần 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 hàm 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"]}' Lưu ý: Ví dụ trước là dành cho các hệ thống dựa trên macOS hoặc Linux, bao gồm cả shell Git BASH cho Windows. Các hệ thống khác có thể cần sửa đổi một chút. Ví dụ: dòng lệnh cmd.exe không cho phép dấu ngoặc đơn cho các tham số cũng như không cho phép tiếp tục dòng (), vì vậy, bạn phải sử dụng dấu ngoặc kép (thoát khỏi dấu ngoặc kép bên trong khi thích hợp với ") và cũng sử dụng một dòng.

Bạn có thể truy cập dữ liệu cấp trang thông qua API bằng cách truyề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ì tất cả chỉ số hiện có sẽ được trả về:

• cumulative_layout_shift
• first_contentful_paint
• 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ị 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ý thông qua một quy trình để hợp nhất, tổng hợp và lọc dữ liệu trước khi có thể sử dụng bằ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à giá trị 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 bất kỳ thời điểm nào thực sự là dữ liệu của 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 các báo cáo hằng thá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 theo giờ UTC. Không có thoả thuận mức độ cung cấp dịch vụ nào về thời gian cập nhật; quá trình này được chạy dựa trên nỗ lực tốt nhất mỗi ngày.

Thận trọng: Dữ liệu sẽ không thay đổi trong cùng một ngày sau khi được cập nhật vào khoảng 4:00 (giờ UTC). Các lệnh gọi lặp lại sẽ trả về cùng một kết quả.

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ề nguồn 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:

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

enum (FormFactor)

Hệ số hình dạng là một phương diện truy vấn chỉ định lớp thiết bị mà dữ liệu của bản ghi thuộc về.

Trường này sử dụng các giá trị DESKTOP, PHONE hoặc TABLET.

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 có dữ liệu tổng hợp trên tất cả các hệ số hình dạng.

metrics[]

string

Các chỉ số cần đưa vào phản hồi. Nếu bạn không chỉ định chỉ số nào, thì hệ thống sẽ trả về mọi chỉ số tìm thấy.

Giá trị được phép: ["cumulative_layout_shift", "first_contentful_paint", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]

Trường hợp hợp nhất url_pattern. url_pattern là giá trị nhận dạng chính cho một lượt tra cứu bản ghi. Chỉ có thể là một trong những loại sau: origin

string

"Nguồn gốc" url_pattern đề cập đến một mẫu URL là nguồn gốc của một trang web.

Ví dụ: "https://example.com", "https://cloud.google.com"

url

string

url_pattern url đề cập đến một mẫu URL là bất kỳ URL tuỳ ý nào.

Ví dụ: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Ví dụ: để yêu cầu giá trị thời gian 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 có đố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ụ: nội dung phản hồi cho phần 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.

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

enum (FormFactor)

Kiểu 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 không chỉ định kiểu dáng thiết bị, thì hệ thống sẽ trả về dữ liệu tổng hợp trên tất cả kiểu dáng thiết bị.

Trường hợp hợp nhất url_pattern. Mẫu URL là URL mà bản ghi áp dụng. url_pattern chỉ có thể là một trong những giá trị sau: origin

string

origin chỉ định nguồn gốc của bản ghi này.

Lưu ý: Khi chỉ định origin, dữ liệu cho các lượt tải trong nguồn gốc này trên tất cả các trang sẽ được tổng hợp thành dữ liệu trải nghiệm người dùng ở cấp nguồn gốc.

url

string

url chỉ định một URL cụ thể mà bản ghi này dành cho.

Lưu ý: Khi chỉ định url, chỉ dữ liệu cho URL cụ thể đó mới được tổng hợp.

Chỉ số

metric là một tập hợp dữ liệu trải nghiệm người dùng tổng hợp cho một chỉ số hiệu suất web, chẳng hạn như lượt vẽ nội dung đầu tiên. Tệp này có thể chứa biểu đồ tóm tắt về mức sử dụng Chrome trong thực tế dưới dạng một loạt 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[]

object (Bin)

Biểu đồ tần suất của trải nghiệm người dùng cho một chỉ số. Biểu đồ sẽ có ít nhất một vùng chứa và mật độ của tất cả các vùng chứa sẽ cộng lại bằng khoảng 1.

percentiles

object (Percentiles)

Các phân vị hữu ích phổ biến của Chỉ số. Loại giá trị cho các phân vị sẽ giống với loại giá trị được cung cấp cho các vùng chứa Biểu đồ thanh.

fractions

object (Fractions)

Đối tượng này chứa các phân số được gắn nhãn, tổng cộng là ~1.

Phân số được làm tròn đến 4 chữ số thập phân.

Thùng

bin là một phần dữ liệu riêng biệt trải dài từ đầu đến cuối hoặc nếu không có điểm cuối được cung cấp từ đầu đến vô cực dương.

Giá trị bắt đầu và kết thúc của một nhóm được cung cấp theo loại giá trị của chỉ số mà nhóm đó đại diện. Ví dụ: lượt vẽ nội dung đầu tiên được đo bằng mili giây và hiển thị dưới dạng int, do đó, các bộ chứa chỉ số sẽ sử dụng int32 cho các loại bắt đầu và kết thúc. Tuy nhiên, độ lệch bố cục tích luỹ được đo bằng số thập phân không có đơn vị và được hiển thị dưới dạng số thập phân được mã hoá dưới dạng chuỗi, do đó, các nhóm chỉ số của độ lệch bố cục tích luỹ sẽ sử dụng chuỗi cho loại giá trị.

{ "start": value, "end": value, "density": number } Trường start

(integer | string)

Start (Bắt đầu) là phần đầu của vùng chứa dữ liệu.

end

(integer | string)

End (Kết thúc) là phần cuối của vùng chứa dữ liệu. Nếu không điền giá trị cho end, thì vùng chứa sẽ không có điểm cuối và hợp lệ từ start đến +inf.

density

number

Tỷ lệ phần trăm người dùng đã trải nghiệm giá trị của nhóm 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 các 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. Các chỉ số này được dùng để ước tính giá trị của một chỉ số theo tỷ lệ phần trăm người dùng trong tổng số người dùng.

{ "P75": value } Trường p75

(integer | string)

75% số lượt tải trang có chỉ số nhất định ở mức bằng hoặc thấp hơn giá trị này.

Phân số

Fractions chứa các phân số được gắn nhãn có tổng cộng ~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ì 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 }

Tương tự như các giá trị mật độ trong các bộ chứa biểu đồ, mỗi fraction là một số 0.0 <= value <= 1.0 và chúng cộng lại bằng ~1.0.

UrlNormalization

Đối tượng đại diện cho các hành động chuẩn hoá được thực hiện để chuẩn hoá URL nhằm tăng cơ hội tra cứu thành công. Đây là những thay đổi tự động đơn giản được thực hiện khi tìm nạp url_pattern được cung cấp sẽ không thành công. Các thao tác phức tạp như theo lệnh chuyển hướng sẽ không được xử lý.

{ "originalUrl": string, "normalizedUrl": string } Trường originalUrl

string

URL được yêu cầu ban đầu trước khi thực hiện bất kỳ hành động chuẩn hoá nào.

normalizedUrl

string

URL sau khi thực hiện bất kỳ hành động chuẩn hoá nào. Đây là một URL trải nghiệm người dùng hợp lệ và có thể được tra cứu một cách hợp lý.

Giới hạn số lượng yêu cầu

CrUX API được giới hạn ở 150 truy vấn mỗi phút cho mỗi dự án Google Cloud và được cung cấp miễn phí. Bạn có thể xem hạn mức này và mức sử dụng hiện tại trong Google Cloud Console. Hạn mức hào phóng này sẽ đủ cho hầu hết các trường hợp sử dụng và bạn không thể trả tiền để tăng hạn mức.