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 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) 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 tiên trên BigQuery, dữ liệu thực tế 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, Trang tổng quan CrUX và báo cáo Các chỉ số quan trọng về trang web của Search Console, cho phép nhà phát triển đo lường và theo dõi trải nghiệm của người dùng thực. Phần còn thiếu 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à RESTful 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 được thông báo về 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 đơn giản, nhanh chóng và toàn diện vào dữ liệu CrUX. API CrUX 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ư API PageSpeed Insights hiện tại, API này cũng báo cáo dữ liệu trong phòng thí nghiệm từ các quy trình kiểm tra hiệu suất của Lighthouse. API CrUX được tinh giản và có thể phân phát nhanh dữ liệu trải nghiệm người dùng, nhờ đó 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 tất cả các chỉ số quan trọng nhất (Chỉ số quan trọng chính của trang web), API CrUX sẽ kiểm tra và theo dõi 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à cấp URL.

Hãy cùng tìm hiểu cách sử dụng tính năng này!

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

Hãy làm thử!

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ả trải nghiệm cơ bản ở cấp trang. Ví dụ sau đây 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 bao 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 rằng nội dung yêu cầu chứa JSON.
  3. Phần nội dung yêu cầu được mã hoá JSON, chỉ định nguồn gốc https://web.dev.

Để thực hiện cùng một việc trong JavaScript, hãy sử 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ả tính năng hỗ trợ theo lô và nhật ký).

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 phần 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, phản hồi API sẽ là một đối tượng được mã hoá JSON chứa chỉ số thể hiện 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 vùng chứa biểu đồ và bách 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 thể hiện phạm vi giá trị mà người dùng trải nghiệm đối với 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 về 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 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 về phần 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, API CrUX sẽ phản hồi bằng 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ể truy cập công khai. 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 và 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 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 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ể được 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, 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 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 này.

Truy vấn dữ liệu URL

Bạn đã xem 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 sử 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 tham số url trong phần 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, API sẽ trả về một 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ư dự kiế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 mức phân phối trên toàn nguyên gốc.

Chuẩn hoá URL

API CrUX có thể chuẩn hoá các URL được yêu cầu để 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 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 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 xem chi tiết về 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 API CrUX.

API này hỗ trợ ba 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 phần 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 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 về 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 phần 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 hồi cấu hình yêu cầu formFactor để xác nhận rằng chỉ bao gồm trải nghiệm trên điện thoại.

Hãy nhớ lại phần trước, 85% trải nghiệm người dùng trên trang này có LCP "tốt". 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 có thể làm nổi bật sự khác biệt rõ ràng hơn về trải nghiệm người dùng.

Đánh giá hiệu suất của Các chỉ số quan trọng về 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ức phân phối trải nghiệm có thể được coi là "tốt" hay không. Trong ví dụ sau, chúng ta sử dụng API CrUX 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 được điểm đá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).

Khi kết hợp với một cách thức tự động để theo dõi kết quả API, bạn có thể sử dụng dữ liệu từ CrUX để đảm bảo trải nghiệm của người dùng thực nhanh chóng và luôn nhanh chóng. Để biết thêm thông tin về Chỉ số quan trọng chính của trang web và cách đo lường các chỉ số này, hãy xem bài viết Chỉ số quan trọng chính 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ỉ là một phần nhỏ trong những loại thông tin chi tiết có thể có được bằng CrUX. Những 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
    • nhiều phân vị hơn

Hãy xem tài liệu chính thức về API CrUX để 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 câu hỏi hoặc ý kiến phản hồi của bạn. 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.