Xuất bản: Ngày 7 tháng 2 năm 2023, Lần cập nhật gần đây nhất: Ngày 11 tháng 4 năm 2025
Hướng dẫn này giới thiệu điểm cuối Chrome UX Report (CrUX) History API. Điểm cuối này cung cấp chuỗi thời gian của dữ liệu hiệu suất web. Dữ liệu này được cập nhật hằng tuần và cho phép bạn xem khoảng 6 tháng dữ liệu trước đây, với 40 điểm dữ liệu cách nhau 1 tuần.
Khi sử dụng cùng với thông tin cập nhật hằng ngày từ điểm cuối CrUX API ban đầu, giờ đây, bạn có thể nhanh chóng xem cả dữ liệu gần đây nhất và những gì đã xảy ra trước đó. Nhờ vậy, đây là một công cụ mạnh mẽ để xem các thay đổi của trang web theo thời gian.
Dùng thử API trên trang này
Truy vấn CrUX API hằng ngày
Để tóm tắt từ một bài viết trước về CrUX API, bạn có thể lấy ảnh chụp nhanh dữ liệu trường cho một nguồn cụ thể theo cách sau:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" --header 'Content-Type: application/json' --data '{"origin": "https://web.dev"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Thông tin tổng quan nhanh này bao gồm các giá trị mật độ biểu đồ và giá trị phân vị cho một khoảng thời gian thu thập cụ thể là 28 ngày, trong trường hợp này là từ ngày 27 tháng 12 năm 2022 đến ngày 23 tháng 1 năm 2023.
Truy vấn CrUX History API
Để gọi điểm cuối lịch sử, hãy thay đổi queryRecord trong URL thành queryHistoryRecord trong lệnh curl. Bạn có thể sử dụng cùng một khoá CrUX API như đối với lệnh gọi trước.
collectionPeriodCount chỉ định số lượng mục nhập chuỗi thời gian cần trả về; tối đa là 40. Nếu không được chỉ định, giá trị mặc định sẽ là 25.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev", "collectionPeriodCount": 40}'
Hình dạng tổng thể của một phản hồi tương tự nhau, nhưng có nhiều dữ liệu hơn! Thay vì một điểm dữ liệu duy nhất, giờ đây, có các chuỗi thời gian cho những trường chứa giá trị mật độ biểu đồ và giá trị phần trăm thứ 75 (p75).
{
"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 }
}
]
}
}
Trong ví dụ này, chuỗi thời gian densities cho nhóm từ 0 đến 2500 mili giây của chỉ số Thời gian hiển thị nội dung lớn nhất (LCP) là [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. Mỗi mật độ này được quan sát trong mục nhập collectionPeriods tương ứng. Ví dụ: mật độ thứ năm là 0,9183, đây là mật độ của khoảng thời gian thu thập thứ năm, kết thúc vào ngày 3 tháng 9 năm 2022 và 0,9187 là mật độ trong khoảng thời gian kết thúc vào tuần sau đó.
Nói cách khác, khi diễn giải các mục chuỗi thời gian gần đây nhất trong ví dụ về https://web.dev, chúng tôi nhận thấy rằng từ ngày 14 tháng 8 năm 2022 đến ngày 10 tháng 9 năm 2022, 91, 87% số lượt tải trang có giá trị LCP nhỏ hơn 2500 mili giây, 5, 27% có giá trị từ 2500 mili giây đến 4000 mili giây và 2, 85% có giá trị lớn hơn 4000 mili giây.
Tương tự, có một chuỗi thời gian cho các giá trị p75: LCP p75 từ ngày 14 tháng 8 năm 2022 đến ngày 10 tháng 9 năm 2022 là 1377. Điều này có nghĩa là trong khoảng thời gian thu thập này, 75% trải nghiệm người dùng có LCP dưới 1377 mili giây và 25% trải nghiệm người dùng có LCP lớn hơn 1377 mili giây.
Mặc dù ví dụ này chỉ liệt kê 6 mục nhập chuỗi thời gian và khoảng thời gian thu thập, nhưng theo mặc định, các phản hồi từ API sẽ cung cấp 25 mục nhập chuỗi thời gian và tối đa 40 mục nhập khi "collectionPeriodCount": 40 được chỉ định trong yêu cầu. Vì ngày kết thúc của mỗi khoảng thời gian thu thập này là các ngày thứ Bảy cách nhau 7 ngày, nên "collectionPeriodCount": 40 sẽ bao gồm 10 tháng.
Trong bất kỳ phản hồi nào, độ dài của chuỗi thời gian cho mật độ của các bin trong biểu đồ và cho các giá trị p75 sẽ hoàn toàn giống với độ dài của mảng trong trường collectionPeriods: Có mối tương ứng một-một dựa trên chỉ mục trong các mảng này.
Truy vấn dữ liệu ở cấp trang
Ngoài dữ liệu ở cấp nguồn gốc, CrUX History API còn cho phép truy cập vào dữ liệu ở cấp trang trong quá khứ. Mặc dù dữ liệu ở cấp nguồn đã có sẵn trước đây bằng cách sử dụng tập dữ liệu CrUX trên BigQuery, nhưng dữ liệu cũ ở cấp trang chỉ có sẵn nếu các trang web tự thu thập và lưu trữ dữ liệu. API mới hiện cho phép bạn truy cập vào dữ liệu cũ ở cấp trang.
Bạn có thể truy vấn dữ liệu ở cấp trang theo cách tương tự, nhưng sử dụng url thay vì origin trong tải trọng:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Dữ liệu cũ ở cấp trang (và cấp nguồn gốc) phải tuân thủ các yêu cầu tương tự về điều kiện như phần còn lại của CrUX. Do đó, một số trang có thể không có bản ghi đầy đủ về dữ liệu cũ. Trong những trường hợp này, dữ liệu "bị thiếu" sẽ được biểu thị bằng "NaN" cho mật độ histogramTimeseries và null cho percentilesTimeseries. Lý do dẫn đến sự khác biệt này là vì mật độ biểu đồ luôn là số, trong khi các phân vị có thể là số hoặc chuỗi (CLS sử dụng chuỗi, ngay cả khi chúng trông giống như số).
Trực quan hoá dữ liệu
Cách dễ nhất để trực quan hoá dữ liệu là thông qua CrUX Vis, một công cụ được tạo riêng để minh hoạ sức mạnh của CrUX History API. Đọc thêm trong tài liệu về CrUX Vis.
Để tự tạo các biểu đồ tương tự, chúng tôi đã tạo một Colab mẫu. Colab (hay còn gọi là "Colaboratory") cho phép bạn viết và thực thi Python ngay trong trình duyệt. Colab của CrUX History API (nguồn) sử dụng Python để gọi API và lập biểu đồ dữ liệu.
Colab này cho phép bạn tạo biểu đồ p75, biểu đồ 3 bin, lấy dữ liệu ở dạng bảng và xem cặp yêu cầu và phản hồi cho CrUX API bằng cách điền vào một biểu mẫu ngắn. Bạn không cần phải là lập trình viên để sử dụng công cụ này, nhưng chắc chắn bạn có thể xem mã Python và sửa đổi mã đó thành một thứ gì đó tuyệt vời! Hãy thoải mái khám phá và đừng ngại đưa ra ý kiến phản hồi về những gì bạn tìm thấy!
Tất nhiên, bạn không bị giới hạn ở Colab hoặc Python và đây chỉ là một ví dụ về cách sử dụng API mới này. Là một điểm cuối HTTP dựa trên JSON, API này có thể truy vấn từ mọi công nghệ.
Kết luận
Trước khi có điểm cuối CrUX History API, chủ sở hữu trang web chỉ có thể lấy được một số thông tin trước đây từ CrUX. Dữ liệu hằng tháng ở cấp nguồn gốc có sẵn thông qua BigQuery, nhưng dữ liệu hằng tuần và dữ liệu trong quá khứ ở cấp trang thì không có. Chủ sở hữu trang web có thể tự ghi lại dữ liệu này bằng API hằng ngày, nhưng thường thì họ chỉ phát hiện ra nhu cầu này sau khi các chỉ số giảm sút.
Chúng tôi hy vọng rằng việc ra mắt CrUX History API này sẽ giúp chủ sở hữu trang web hiểu rõ hơn về các chỉ số thay đổi của trang web, đồng thời đây cũng là một công cụ chẩn đoán khi vấn đề phát sinh. Nếu bạn đang sử dụng API mới, vui lòng gửi ý kiến phản hồi cho nhóm Google Chrome UX Report (Thảo luận).
Lời cảm ơn
Hình ảnh chính của Dave Herring trên Unsplash