Cách sử dụng API CrUX

Tìm hiểu cách sử dụng Chrome UX Report API để truy cập vào dữ liệu về trải nghiệm của người dùng thực trên hàng triệu trang web.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Tập dữ liệu Báo cáo trải nghiệm người dùng trên Chrome (CrUX) cho biết trải nghiệm thực tế của người dùng Chrome trên những trang web phổ biến. Kể từ năm 2017, khi tập dữ liệu có thể truy vấn được phát hành lần đầu trên BigQuery, dữ liệu hiện trường từ CrUX đã được tích hợp vào các công cụ dành cho nhà phát triển như PageSpeed Insights và báo cáo Các chỉ số quan trọng chính của trang web của Search Console, cho phép nhà phát triển đo lường và giám sát trải nghiệm của người dùng thực. Công cụ còn thiếu bấy lâu nay là một công cụ cung cấp quyền truy cập miễn phí và theo kiểu REST vào dữ liệu CrUX theo phương thức lập trình. Để giúp thu hẹp khoảng cách đó, chúng tôi rất vui mừng thông báo việc phát hành Chrome UX Report API hoàn toàn mới!

API này được xây dựng với mục tiêu cung cấp cho nhà phát triển quyền truy cập nhanh chóng và toàn diện vào dữ liệu CrUX. CrUX API chỉ báo cáo dữ liệu trải nghiệm người dùng thực tế tại trang, không giống như PageSpeed Insights API hiện có, API này cũng báo cáo dữ liệu phòng thí nghiệm từ các quy trình kiểm tra hiệu suất của Lighthouse. CrUX API được tinh giản và có thể nhanh chóng phân phát dữ liệu trải nghiệm người dùng, nhờ đó, API này rất phù hợp với các ứng dụng kiểm tra theo thời gian thực.

Để đảm bảo nhà phát triển có quyền truy cập vào tất cả các chỉ số quan trọng nhất (Chỉ số quan trọng chính của trang web), CrUX API sẽ kiểm tra và giám sát Nội dung lớn nhất hiển thị (LCP), Lượt tương tác đến nội dung hiển thị tiếp theo (INP) và Mức thay đổi bố cục tích luỹ (CLS) ở cả cấp nguồn gốc và URL.

Vậy hãy cùng tìm hiểu cách sử dụng công cụ này!

Dùng thử API trên trang này

Hãy làm thử!

Truy vấn dữ liệu gốc

Các nguồn gốc trong tập dữ liệu CrUX bao gồm tất cả trải nghiệm cấp trang cơ bản. Ví dụ sau đây minh hoạ cách truy vấn API CrUX để lấy dữ liệu trải nghiệm người dùng của một nguồn bằng cách sử dụng curl trên dòng lệnh.

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

Lệnh curl bao gồm 3 phần:

  1. Điểm cuối URL của API, bao gồm cả khoá API riêng tư của phương thức gọi.
  2. Tiêu đề Content-Type: application/json, cho biết rằng nội dung yêu cầu chứa JSON.
  3. Nội dung yêu cầu được mã hoá bằng JSON, chỉ định nguồn gốc https://web.dev.

Để làm điều tương tự trong JavaScript, hãy dùng tiện ích CrUXApiUtil. Tiện ích này sẽ thực hiện lệnh gọi API và trả về phản hồi đã giải mã (xem thêm biến thể Github của chúng tôi để biết thêm các tính năng, bao gồm cả nhật ký và hỗ trợ hàng loạt).

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

Thay thế [YOUR_API_KEY] bằng khoá của bạn. Tiếp theo, hãy gọi hàm CrUXApiUtil.query và truyền vào đối tượng nội dung yêu cầu.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Nếu có dữ liệu cho nguồn gốc này, thì phản hồi API sẽ là một đối tượng được mã hoá JSON chứa metrics (chỉ số) biểu thị mức độ phân phối trải nghiệm người dùng. Các chỉ số phân phối là các bin và phân vị của biểu đồ.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            "density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

Các thuộc tính start và end của đối tượng histogram biểu thị phạm vi giá trị mà người dùng trải nghiệm cho chỉ số đã cho. Thuộc tính density thể hiện tỷ lệ trải nghiệm người dùng trong phạm vi đó. Trong ví dụ này, 79% trải nghiệm người dùng LCP trên tất cả các trang web.dev đều dưới 2.500 mili giây, đây là ngưỡng LCP "tốt". Giá trị percentiles.p75 có nghĩa là 75% trải nghiệm người dùng trong bản phân phối này dưới 2.216 mili giây. Tìm hiểu thêm về cấu trúc phản hồi trong tài liệu nội dung phản hồi.

Lỗi

Khi không có dữ liệu nào cho một nguồn gốc nhất định, CrUX API sẽ phản hồi bằng một thông báo lỗi được mã hoá bằng JSON:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

Để gỡ lỗi này, trước tiên, hãy kiểm tra xem nguồn được yêu cầu có thể truy cập công khai hay không. Bạn có thể kiểm tra điều này bằng cách nhập nguồn gốc vào thanh địa chỉ của trình duyệt rồi so sánh với URL cuối cùng sau mọi lệnh chuyển hướng. Các vấn đề thường gặp bao gồm việc thêm hoặc bỏ qua miền con một cách không cần thiết và sử dụng giao thức HTTP không chính xác.

Lỗi
{"origin": "http://www.web.dev"}

Nguồn gốc này bao gồm giao thức http:// và miền con www. không chính xác.

Thành công
{"origin": "https://web.dev"}

Nguồn gốc này có thể truy cập công khai.

Nếu nguồn gốc được yêu cầu là phiên bản có thể điều hướng, thì lỗi này cũng có thể xảy ra nếu nguồn gốc có số lượng mẫu không đủ. Tất cả nguồn gốc và URL có trong tập dữ liệu phải có đủ số lượng mẫu để ẩn danh người dùng cá nhân. Ngoài ra, nguồn gốc và URL phải có thể lập chỉ mục công khai. Hãy tham khảo phương pháp CrUX để tìm hiểu thêm về cách các trang web được đưa vào tập dữ liệu.

Truy vấn dữ liệu URL

Bạn đã thấy cách truy vấn CrUX API để biết trải nghiệm tổng thể của người dùng trên một nguồn gốc. Để hạn chế kết quả đối với một trang cụ thể, hãy sử dụng tham số yêu cầu url.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

Lệnh curl này tương tự như ví dụ về nguồn gốc, ngoại trừ việc phần nội dung yêu cầu sử dụng tham số url để chỉ định trang cần tra cứu.

Để truy vấn dữ liệu URL từ CrUX API bằng JavaScript, hãy gọi hàm CrUXApiUtil.query bằng cách sử dụng tham số url trong nội dung yêu cầu.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Nếu có dữ liệu cho URL này trong tập dữ liệu CrUX, API sẽ trả về một phản hồi được mã hoá bằng JSON. Ví dụ

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

Đúng như dự đoán, kết quả cho thấy https://web.dev/fast/ có 85% trải nghiệm LCP "tốt" và phân vị thứ 75 là 1.947 mili giây, cao hơn một chút so với phân phối trên toàn nguồn gốc.

Chuẩn hoá URL

CrUX API có thể chuẩn hoá các URL được yêu cầu để so khớp tốt hơn với danh sách URL đã biết. Ví dụ: việc truy vấn URL https://web.dev/fast/#measure-performance-in-the-field sẽ dẫn đến dữ liệu cho https://web.dev/fast/ do quá trình chuẩn hoá. Khi điều này xảy ra, một đối tượng urlNormalizationDetails sẽ được đưa vào phản hồi.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

Tìm hiểu thêm về quy trình chuẩn hoá URL trong tài liệu CrUX.

Truy vấn theo hệ số hình dạng

Trải nghiệm của người dùng có thể khác nhau đáng kể tuỳ thuộc vào việc tối ưu hoá trang web, điều kiện mạng và thiết bị của người dùng. Để hiểu rõ hơn về những điểm khác biệt này, hãy đi sâu vào hiệu suất của nguồn gốc và URL bằng cách sử dụng phương diện formFactor của CrUX API.

API này hỗ trợ 3 giá trị hệ số hình dạng rõ ràng: DESKTOP, PHONE và TABLET. Ngoài nguồn gốc hoặc URL, hãy chỉ định một trong các giá trị này trong nội dung yêu cầu để chỉ giới hạn kết quả ở những trải nghiệm người dùng đó. Ví dụ này minh hoạ cách truy vấn API theo kiểu dáng thiết bị bằng cách sử dụng lệnh curl.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

Để truy vấn CrUX API để lấy dữ liệu dành riêng cho hệ số hình dạng bằng JavaScript, hãy gọi hàm CrUXApiUtil.query bằng các tham số url và formFactor trong nội dung yêu cầu.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Việc bỏ qua thông số formFactor tương đương với việc yêu cầu dữ liệu cho tất cả các kiểu dáng thiết bị kết hợp.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

Trường key của phản hồi sẽ phản ánh lại cấu hình yêu cầu formFactor để xác nhận rằng chỉ có trải nghiệm trên điện thoại được đưa vào.

Hãy nhớ lại từ phần trước rằng 85% trải nghiệm người dùng trên trang này có LCP "tốt". Hãy so sánh với trải nghiệm dành riêng cho điện thoại, trong đó chỉ có 78% được coi là "tốt". Phân vị thứ 75 cũng chậm hơn trong số các trải nghiệm trên điện thoại, tăng từ 1.947 mili giây lên 2.366 mili giây. Việc phân đoạn theo hệ số hình dạng có thể làm nổi bật những khác biệt lớn hơn về trải nghiệm người dùng.

Đánh giá hiệu suất Các chỉ số quan trọng chính của trang web

Chương trình Các chỉ số quan trọng về trang web xác định các mục tiêu giúp xác định xem trải nghiệm người dùng hoặc một nhóm trải nghiệm có thể được coi là "tốt" hay không. Trong ví dụ sau, chúng ta sẽ sử dụng CrUX API và hàm CrUXApiUtil.query để đánh giá xem mức phân phối các chỉ số Core Web Vitals (LCP, INP, CLS) của một trang web có "tốt" hay không.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the "good" threshold.
    const passes = p75 < threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

Kết quả cho thấy trang này đạt yêu cầu đánh giá Core Web Vitals cho cả 3 chỉ số.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

Kết hợp với một cách tự động để theo dõi kết quả API, bạn có thể sử dụng dữ liệu từ CrUX để đảm bảo rằng trải nghiệm của người dùng thực tế nhanh chóng và luôn nhanh chóng. Để biết thêm thông tin về Core Web Vitals và cách đo lường các chỉ số này, hãy xem Web Vitals và Các công cụ đo lường Core Web Vitals.

Tiếp theo là gì?

Các tính năng có trong phiên bản đầu tiên của CrUX API chỉ là một phần nhỏ trong số những thông tin chi tiết có thể có được nhờ CrUX. Người dùng tập dữ liệu CrUX trên BigQuery có thể đã quen thuộc với một số tính năng nâng cao hơn, bao gồm:

  • Các chỉ số khác
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Các phương diện bổ sung
    • month
    • country
  • Độ chi tiết bổ sung
    • biểu đồ chi tiết
    • nhiều phân vị hơn

Hãy xem tài liệu chính thức về CrUX API để lấy khoá API và khám phá thêm các ứng dụng mẫu. Chúng tôi hy vọng bạn sẽ dùng thử và rất mong nhận được mọi câu hỏi hoặc ý kiến phản hồi của bạn. Vì vậy, hãy liên hệ với chúng tôi trên diễn đàn thảo luận về CrUX. Để nắm bắt thông tin mới nhất về mọi thứ chúng tôi đã lên kế hoạch cho CrUX API, hãy đăng ký theo dõi diễn đàn thông báo về CrUX hoặc theo dõi chúng tôi trên Twitter tại @ChromeUXReport.