Cách sử dụng API CrUX

Tìm hiểu cách sử dụng API Báo cáo trải nghiệm người dùng trên Chrome để truy cập vào dữ liệu về trải nghiệm 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) thể hiện cách người dùng Chrome trong thực tế trải nghiệm các điểm đến phổ biến trên web. 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 trường trên CrUX đã được tích hợp vào các công cụ cho nhà phát triển như PageSpeed Insights, Trang tổng quan CrUX và báo cáo Chỉ số quan trọng chính của trang web của Search Console. Nhờ đó, các nhà phát triển có thể đo lường và giám sát trải nghiệm thực tế của người dùng. Phần bị bỏ lỡ trong suốt thời gian qua là một công cụ cung cấp quyền truy cập miễn phí và theo định dạng RESTful vào dữ liệu CrUX theo phương thức lập trình. Để thu hẹp khoảng cách đó, chúng tôi vui mừng thông báo về việc phát hành API Báo cáo trải nghiệm người dùng của Chrome 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 đơn giản, nhanh chóng và toàn diện vào dữ liệu CrUX. Không giống như PageSpeed Insights API hiện có, API CrUX chỉ báo cáo dữ liệu về trải nghiệm người dùng trường, vốn cũng báo cáo dữ liệu của phòng thí nghiệm trong các cuộc 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, khiến API này phù hợp lý tưởng cho 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 mọi chỉ số quan trọng nhất (Các chỉ số quan trọng về trang web), CrUX API sẽ kiểm tra và giám sát Nội dung lớn nhất hiển thị (LCP), Tương tác với Nội dung lớn nhất hiển thị (INP) và Điểm số tổng hợp về mức thay đổi bố cục (CLS) ở cả cấp độ nguồn gốc lẫn cấp URL.

Vì vậy, hãy tìm hiểu kỹ hơn và tìm hiểu cách sử dụng tính năng này!

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

Nguồn gốc trong tập dữ liệu CrUX bao gồm tất cả các trải nghiệm cơ bản ở cấp trang. Ví dụ sau minh hoạ cách truy vấn API CrUX để biết dữ liệu trải nghiệm người dùng của một nguồn gốc 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 gồm ba 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 nội dung yêu cầu chứa JSON.
  3. Nội dung yêu cầu được mã hoá JSON, chỉ định nguồn gốc https://web.dev.

Để thực hiện tương tự trong JavaScript, hãy sử dụng tiện ích CrUXApiUtil, phương thức này 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 để biết thêm các tính năng khác, bao gồm cả lịch sử và hỗ trợ theo lô).

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 này, thì phản hồi của API là một đối tượng được mã hoá JSON chứa các chỉ số thể hiện việc phân phối trải nghiệm người dùng. Các chỉ số phân phối là thùng biểu đồ và phân vị.

{
  "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
        }
      },
      // ...
    }
  }
}

Thuộc tính start và end của đối tượng histogram đại diện cho khoảng giá trị mà người dùng trải nghiệm đối với chỉ số đã cho. Thuộc tính density đại diện cho 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 là dưới 2.500 mili giây, đây là yếu tố "tốt" Ngưỡng LCP. 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 là 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 về 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á JSON:

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

Để gỡ lỗi lỗi này, trước tiên, hãy kiểm tra để đảm bảo rằng nguồn gốc được yêu cầu có thể điều hướng công khai. Bạn có thể kiểm tra URL 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 bất kỳ lượt chuyển hướng nào. Các vấn đề thường gặp bao gồm việc thêm hoặc bỏ qua miền con không cần thiết và sử dụng sai giao thức HTTP.

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

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

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

Nguồn gốc này có thể điều hướng công khai.

Nếu nguồn gố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 không có đủ số lượng mẫu. 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 từng người dùng. 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 đã biết cách truy vấn API CrUX để 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ả cho 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 dùng tham số url để chỉ định trang cần tra cứu.

Để truy vấn dữ liệu URL từ API CrUX trong 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 dữ liệu cho URL này tồn tại trong tập dữ liệu CrUX, thì API sẽ trả về phản hồi được mã hoá 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ư thực tế, kết quả cho thấy https://web.dev/fast/ có 85% tỷ lệ phần trăm "tốt" Trải nghiệm LCP và phân vị thứ 75 là 1.947 mili giây, tốt hơn một chút so với mức 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 để khớp với danh sách các URL đã biết một cách hiệu quả hơn. Ví dụ: truy vấn URL https://web.dev/fast/#measure-performance-in-the-field sẽ trả về dữ liệu cho https://web.dev/fast/ do 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ề việc chuẩn hoá URL trong tài liệu về CrUX.

Truy vấn theo kiểu dáng thiết bị

Trải nghiệm người dùng có thể khác nhau đáng kể tuỳ thuộc vào cách tối ưu hoá trang web, điều kiện mạng và thiết bị. Để hiểu rõ hơn về những điểm khác biệt này, hãy xem chi tiết về nguồn gốc và hiệu suất của 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ỉ cung cấp kết quả cho 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 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 API CrUX đối với dữ liệu dành riêng cho từng hệ số hình dạng bằng JavaScript, hãy gọi hàm CrUXApiUtil.query bằng cách sử dụng 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 tham số formFactor tương đương với việc yêu cầu dữ liệu cho tất cả các hệ số hình dạng kết hợp lại.

{
  "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ẽ lặp lại cấu hình của yêu cầu formFactor để xác nhận rằng chỉ bao gồm trải nghiệm qua điện thoại.

Hãy nhớ lại phần trước rằng 85% trải nghiệm người dùng trên trang này có điểm "tốt" LCP (Nội dung lớn nhất hiển thị). So sánh với trải nghiệm dành riêng cho điện thoại, trong đó chỉ 78% được coi là "tốt". Phân vị thứ 75 cũng chậm hơn trong 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 kiểu dáng thiết bị có thể làm nổi bật những sự khác biệt quá lớn trong trải nghiệm người dùng.

Đánh giá hiệu suất Core Web Vitals

Chương trình Chỉ số quan trọng chính của trang web đưa ra các mục tiêu giúp xác định xem trải nghiệm người dùng hoặc hoạt động phân phối trải nghiệm có được coi là "tốt" hay không. Trong ví dụ sau, chúng tôi sử dụng API CrUX và hàm CrUXApiUtil.query để đánh giá xem mức độ phân phối của các chỉ số Các chỉ số quan trọng chính của trang web (LCP, INP, CLS) 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/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 vượt qua quy trình đánh giá Core Web Vitals đối với 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 cách tự động để theo dõi kết quả API, dữ liệu từ CrUX có thể được dùng để đảm bảo trải nghiệm người dùng thực trở nên nhanh chóng và duy trì nhanh. Để biết thêm thông tin về Chỉ số quan trọng chính của trang web cũng như cách đo lường, hãy xem các bài viết về Chỉ số quan trọng của trang web và Công cụ đo lường Chỉ số quan trọng chính của trang web.

Tiếp theo là gì?

Các tính năng có trong phiên bản ban đầu của API CrUX chỉ mới đề cập đến những loại thông tin chi tiết khả thi với 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
  • Phương diện bổ sung
    • month
    • country
    • effective connection type (ECT)
  • Độ chi tiết bổ sung
    • biểu đồ chi tiết
    • phân vị khác

Hãy xem các tài liệu chính thức về API CrUX để lấy khoá API của bạn và khám phá các ứng dụng mẫu khác. Chúng tôi hy vọng bạn sẽ dùng thử tính năng này và chúng tôi luôn sẵn sàng lắng nghe mọi câu hỏi cũng như ý 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 nội dung chúng tôi đã lên kế hoạch cho API CrUX, hãy đăng ký diễn đàn thông báo về CrUX hoặc theo dõi chúng tôi trên Twitter tại @ChromeUXReport.