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 của Chrome để có quyền 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

Tập dữ liệu Báo cáo trải nghiệm người dùng của Chrome (CrUX) thể hiện cách người dùng Chrome 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 tiên trên BigQuery, dữ liệu trường của 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 Các chỉ số quan trọng về trang web trong Search Console. Nhờ đó, các nhà phát triển có thể đo lường và theo dõi trải nghiệm thực tế của người dùng. Phần bị thiếu suốt thời gian này là một công cụ cung cấp quyền truy cập miễn phí và REST 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 các 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 trong trường, khác với API PageSpeed Insights hiện có, vốn cũng báo cáo dữ liệu trong phòng thí nghiệm của các lượt kiểm tra hiệu suất trong Lighthouse. API CrUX được sắp xếp hợp lý và có thể nhanh chóng phân phát dữ liệu trải nghiệm người dùng, giúp API CrUX 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ó thể sử dụng tất cả các chỉ số quan trọng nhất (Các chỉ số quan trọng chính của trang web), API CrUX sẽ kiểm tra và theo dõi Thời gian hiển thị nội dung lớn nhất (LCP), Thời gian phản hồi lần tương tác đầu tiên (FID) và Điểm số tổng hợp về mức thay đổi bố cục (CLS) ở cả nguồn gốc lẫn cấp độ URL.

Hãy cùng tìm hiểu kỹ hơn và tìm hiểu cách sử dụng công cụ này!

Dữ liệu gốc truy vấn

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 minh hoạ cách truy vấn API CrUX cho 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ưu ý: Tất cả yêu cầu API đều phải cung cấp một giá trị cho tham số key – [YOUR_API_KEY] trong ví dụ trước được để ở dạng phần giữ chỗ. Nhận khoá API CrUX riêng của bạn như mô tả trong tài liệu về API CrUX.

Lệnh curl 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 nội dung yêu cầu có 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 điều tương tự trong JavaScript, hãy sử dụng tiện ích CrUXApiUtil. Tiện ích này thực hiện lệnh gọi API và trả về phản hồi được 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 khác, 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á. 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 của API là một đối tượng được mã hoá JSON chứa các metrics cho biết việc phân phối trải nghiệm người dùng. 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
        }
      },
      // ...
    }
  }
}

Các thuộc tính start và end của đối tượng histogram đại diện cho phạm vi các giá trị mà người dùng trải nghiệm đối với một chỉ số nhất định. 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 có thời lượng 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 có thời lượng 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, 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 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 đ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 nguồn gốc đó với URL cuối cùng sau bất kỳ lần chuyển hướng nào. Các vấn đề thường gặp bao gồm 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 sai.

Lỗi

{"origin": "http://www.web.dev"}

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

Thành công

{"origin": "https://web.dev"}

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

Nếu điểm 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 điểm 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 người dùng cá nhân. Ngoài ra, các 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 đã xem cách truy vấn API CrUX để cung cấp trải nghiệm tổng thể của người dùng tại một nguồn gốc. Để hạn chế kết quả ở 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 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 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, 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ư biểu mẫu, kết quả cho thấy https://web.dev/fast/ có 85% trải nghiệm LCP "tốt" và tỷ lệ phần trăm 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 bộ nguồn gốc.

Chuẩn hoá URL

API CrUX có thể chuẩn hoá các URL được yêu cầu để phù hợp 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 về https://web.dev/fast/ do quá trình chuẩn hoá. Khi điều này xảy ra, đố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 CrUX.

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

Từ khoá quan trọng: Hệ số hình dạng là loại thiết bị mà người dùng sử dụng để truy cập vào trang web. Các loại thiết bị phổ biến bao gồm máy tính, điện thoại và máy tính bảng.

Trải nghiệm người dùng có thể thay đổi đáng kể tuỳ thuộc vào các chế độ 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 nguồn gốc và hiệu suất của URL bằng phương diện formFactor của API CrUX.

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 để giới hạn kết quả chỉ cho những trải nghiệm người dùng đó. Ví dụ này minh hoạ cách truy vấn API theo hệ số hình 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 cho 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 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 tham số formFactor tương đương với việc yêu cầu dữ liệu cho tất cả hệ số hình dạng 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ẽ lặp lạ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.

Thận trọng: Yêu cầu càng chi tiết, chẳng hạn như một kết hợp cụ thể giữa URL và kiểu dáng, thì càng có ít trải nghiệm người dùng. Điều này có thể dẫn đến lỗi "not found" (không tìm thấy) thường xuyên hơn, đặc biệt là khi truy vấn các URL ít phổ biến hoặc loại thiết bị máy tính bảng ít phổ biến hơn.

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 trải nghiệm đó với trải nghiệm dành riêng cho điện thoại, trong đó chỉ 78% được đánh giá 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ừ 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 sự chênh lệch quá lớ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 liệu một trải nghiệm người dùng hoặc việc 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 việc phân phối các chỉ số Các chỉ số quan trọng về trang web (LCP, FID, 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/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'first_input_delay',
    '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}).`)
  });
}

Lưu ý quan trọng: Bạn chỉ có thể gọi API bằng một nguồn gốc hoặc URL tại mỗi thời điểm. Để đánh giá nhiều trang web hoặc trang, hãy thực hiện các lệnh gọi riêng biệt đến API.

Kết quả cho thấy trang này đã vượt qua quy trình đánh giá Các chỉ số quan trọng về trang web cho cả 3 chỉ số này.

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

Kết hợp với phương pháp tự động để giám sát kết quả API, dữ liệu từ CrUX có thể được sử dụng để đảm bảo rằng trải nghiệm người dùng thực nhanh chóng và luôn nhanh. Để biết thêm thông tin về Các chỉ số quan trọng về trang web và cách đo lường, hãy xem bài viết Các chỉ số quan trọng về trang web và Công cụ đo lường Các chỉ số quan trọng về 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ỉ đề cập đến những loại thông tin chi tiết có thể có 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 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ử tính năng này. Chúng tôi cũng rất mong nhận được ý kiến phản hồi hoặc câu 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 CrUX. Ngoài ra, để nắm bắt mọi thông tin mới nhất về kế hoạch triển khai API CrUX, hãy đăng ký diễn đàn thông báo CrUX hoặc theo dõi chúng tôi trên Twitter tại @ChromeUXReport.