Cách sử dụng API Nhật ký CrUX

Hướng dẫn này giới thiệu điểm cuối API Nhật ký báo cáo trải nghiệm người dùng trên Chrome (CrUX). Điểm cuối này cung cấp dữ liệu về hiệu suất web theo chuỗi thời gian. Dữ liệu này cập nhật hàng tuần và cho phép bạn xem lịch sử trong khoảng 6 tháng, với 25 điểm dữ liệu được cách nhau một tuần.

Giờ đây, khi được sử dụng cùng với các bản cập nhật hằng ngày từ điểm cuối CrUX API ban đầu, bạn hiện có thể xem nhanh cả dữ liệu gần đây nhất lẫn dữ liệu đã xảy ra trước đó. Nhờ đó, công cụ này trở thành một công cụ mạnh mẽ giúp bạn thấy được các thay đổi của trang web theo thời gian.

Truy vấn API CrUX hằng ngày

Để tóm tắt nội dung từ bài viết trước về CrUX API, bạn có thể lấy ảnh chụp nhanh về dữ liệu trường cho một nguồn gốc 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 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 API nhật ký CrUX

Để gọi điểm cuối của nhật ký, 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á API CrUX như đối với lệnh gọi trước đó.

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"}'

Hình dạng tổng thể của câu trả lời sẽ 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, hiện có chuỗi thời gian cho các trường chứa giá trị phân vị thứ 75 (p75) và biểu đồ mật độ.

{
  "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 0 đến 2500 mili giây của chỉ số Nội dung lớn nhất hiển thị (LCP)[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 collectionPeriods tương ứng. Ví dụ: mật độ thứ năm, 0,9183, là mật độ cho giai đoạn 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 giai đoạn kết thúc tuần sau đó.

Nói cách khác, trong quá trình diễn giải các mục chuỗi thời gian gần đây nhất trong ví dụ này cho https://web.dev, chúng tôi nhận thấy rằng từ ngày 14 tháng 8 năm 2022 cho đến ngày 10 tháng 9 năm 2022, 91,87% lượt tải trang có giá trị LCP nhỏ hơn 2500 mili giây, 5,27% có giá trị trong khoảng từ 2500 mili giây đến 4008% và có giá trị lớn hơn 0,2 mili giây, 0,4%

Tương tự, các giá trị p75 có một chuỗi thời gian: LCP p75 từ ngày 14 tháng 8 năm 2022 cho đế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.

Trong khi 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, các phản hồi từ API cung cấp 25 mục nhập chuỗi thời gian; vì ngày kết thúc của mỗi kỳ thu thập này là những ngày thứ Bảy cách nhau 7 ngày, nên khoảng thời gian này là 6 tháng.

Trong một phản hồi cho trước bất kỳ, độ dài của chuỗi thời gian cho mật độ thùng biểu đồ và của các giá trị p75 sẽ giống hệt với độ dài mảng trong trường collectionPeriods: Có sự tương ứng một với một dựa trên chỉ mục thành các mảng này.

Truy vấn dữ liệu cấp trang

Cũng như dữ liệu cấp độ gốc, CrUX History API cho phép truy cập vào dữ liệu trong quá khứ ở cấp trang. Mặc dù trước đây dữ liệu cấp gốc có sẵn bằng cách sử dụng tập dữ liệu CrUX trên BigQuery (hoặc thông qua Trang tổng quan CrUX), nhưng dữ liệu trong quá khứ ở cấp trang chỉ có sẵn nếu các trang web tự thu thập và lưu trữ dữ liệu đó. Giờ đây, API mới sẽ mở khoá dữ liệu cấp trang trước đây.

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 trong quá khứ ở cấp trang (và cấp gốc) phải tuân theo các yêu cầu tương tự như những trang còn lại của CrUX, do đó, các trang cụ thể có thể không có dữ liệu lịch sử đầy đủ. Trong những trường hợp này, thẻ "bị thiếu" dữ liệu sẽ được biểu thị bằng "NaN" cho mật độ histogramTimeseriesnull cho percentilesTimeseries. Nguyên nhân là do mật độ của biểu đồ luôn ở dạng số, trong khi phân vị có thể là số hoặc chuỗi (CLS sử dụng chuỗi, ngay cả khi các phân vị đó trông giống số).

Trực quan hoá dữ liệu

Vì vậy, có thể bạn sẽ đặt câu hỏi, tại sao dữ liệu được định hình theo cách này? Người ta nhận thấy rằng điều này giúp vẽ đồ thị dễ dàng hơn. Ví dụ: sau đây là biểu đồ về các giá trị p75 cho Tương tác với nội dung hiển thị tiếp theo (INP) cho https://web.dev:

Biểu đồ chuỗi thời gian về giá trị p75 cho thấy sự hồi quy vào khoảng tháng 11 năm 2022

Trong biểu đồ dạng đường này, mỗi giá trị trên trục y là một giá trị p75 trong chuỗi thời gian p75s, còn trục x là thời gian, được thiết lập là lastDate cho mỗi khoảng thời gian thu thập.

Dưới đây là biểu đồ của chuỗi thời gian thùng biểu đồ – được gọi là biểu đồ ba thùng – vì những biểu đồ này có 3 thùng.

Biểu đồ thanh xếp chồng cho thấy tỷ lệ tương đối giữa các yếu tố tốt, cần cải thiện và những thay đổi kém theo thời gian.

Trục x được thiết lập thành lastDate cho mỗi khoảng thời gian thu thập. Tuy nhiên, lần này trục y là tỷ lệ phần trăm số lượt tải trang rơi vào một phạm vi cụ thể cho chỉ số INP, được thể hiện qua biểu đồ thanh xếp chồng. Biểu đồ p75 cung cấp thông tin tổng quan nhanh. Trong một biểu đồ, bạn có thể dễ dàng thêm nhiều chỉ số hoặc hiển thị các đường cho cả PHONEDESKTOP. Biểu đồ 3 thùng cho biết sự phân bổ của các giá trị chỉ số được đo lường trong từng khoảng thời gian thu thập.

Ví dụ: mặc dù biểu đồ p75 cho thấy rằng https://web.dev có các giá trị INP gần như chấp nhận được trong giai đoạn quan sát, nhưng biểu đồ 3 thùng cho thấy rằng đối với một phần nhỏ số lượt tải trang, INP thực sự kém. Trong cả hai biểu đồ, bạn có thể dễ dàng dự đoán rằng có sự hồi quy hiệu suất bắt đầu vào cuối tháng 10 và được khắc phục vào giữa tháng 11.

Để tự tạo các biểu đồ như vậy, chúng tôi đã tạo một mẫu Colab. 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 API nhật ký CrUX (nguồn) sử dụng Python để thực hiện lệnh gọi đến API và lập biểu đồ dữ liệu.

Colab này cho phép bạn tạo biểu đồ p75, biểu đồ ba thùng, nhận dữ liệu ở dạng bảng cũng như xem cặp yêu cầu và phản hồi cho API CrUX 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 mới có thể sử dụng được mã này. Tuy nhiên, chắc chắn bạn có thể xem mã Python và sửa đổi mã đó thành một thứ tuyệt vời! Hãy trải nghiệm 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 hay Python và đây chỉ là một ví dụ về cách sử dụng API mới này. Dựa trên JSON, điểm cuối HTTP mà API có thể truy vấn được từ bất kỳ công nghệ nào.

Kết luận

Trước khi điểm cuối CrUX History API ra mắt, chủ sở hữu trang web không được phép cung cấp nhiều thông tin trong quá khứ mà CrUX có thể thu thập được. Có dữ liệu cấp độ gốc hằng tháng qua BigQuery và Trang tổng quan CrUX, nhưng không có dữ liệu hằng tuần và cũng không có dữ liệu trong quá khứ cấp trang. Chủ sở hữu trang web có thể tự ghi lại dữ liệu này bằng cách sử dụng API hằng ngày, nhưng thông thường, người dùng chỉ phát hiện ra nhu cầu này sau khi các chỉ số trở nên hồi quy.

Chúng tôi hy vọng rằng CrUX History API sẽ giúp chủ sở hữu trang web hiểu rõ hơn về các chỉ số liên quan đến thay đổi của trang web cũng như là một công cụ chẩn đoán khi có vấn đề phát sinh. Nếu bạn đang sử dụng API mới, chúng tôi rất mong nhận được ý kiến phản hồi tại nhóm Google Báo cáo trải nghiệm người dùng Chrome (Thảo luận).

Xác nhận

Hình ảnh chính của Dave Herring trên Unsplash