API CrUX

CrUX API cung cấp quyền truy cập có độ trễ thấp vào dữ liệu tổng hợp về trải nghiệm của người dùng thực ở mức độ chi tiết của trang và nguồn gốc.

Hãy làm thử!

Trường hợp sử dụng phổ biến

CrUX API cho phép truy vấn các chỉ số về trải nghiệm người dùng cho một URI cụ thể, chẳng hạn như "Nhận các chỉ số cho nguồn https://example.com".

Khoá API CrUX

Để sử dụng CrUX API, bạn cần có khoá Google Cloud API được cấp phép để sử dụng Chrome UX Report API.

Lấy và sử dụng khoá API

Hoặc tạo một khoá trên Trang thông tin xác thực.

Sau khi có khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=yourAPIKey vào tất cả URL yêu cầu.

Khoá API an toàn khi nhúng vào URL; khoá này không cần mã hoá.

Xem Truy vấn mẫu.

Mô hình dữ liệu

Phần này trình bày chi tiết cấu trúc dữ liệu trong các yêu cầu và phản hồi.

Ghi âm

Một phần thông tin riêng biệt về một trang hoặc trang web. Một bản ghi có thể có dữ liệu dành riêng cho một giá trị nhận dạng và cho một tổ hợp phương diện cụ thể. Một bản ghi có thể chứa dữ liệu cho một hoặc nhiều chỉ số.

Giá trị nhận dạng

Giá trị nhận dạng chỉ định những bản ghi cần được tra cứu. Trong CrUX, các giá trị nhận dạng này là trang web và trang web.

Điểm gốc

Khi giá trị nhận dạng là một nguồn gốc, tất cả dữ liệu hiện có cho tất cả các trang trong nguồn gốc đó sẽ được tổng hợp lại với nhau. Ví dụ: giả sử nguồn gốc http://www.example.com có các trang được bố trí theo sơ đồ trang web sau:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Điều này có nghĩa là khi truy vấn Báo cáo trải nghiệm người dùng trên Chrome với nguồn gốc được đặt thành http://www.example.com, dữ liệu cho http://www.example.com/, http://www.example.com/foo.html và http://www.example.com/bar.html sẽ được trả về, tổng hợp lại với nhau, vì đó đều là các trang thuộc nguồn gốc đó.

URL

Khi giá trị nhận dạng là một URL, chỉ dữ liệu cho URL cụ thể đó mới được trả về. Hãy xem lại sơ đồ trang web của nguồn gốc http://www.example.com:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Nếu giá trị nhận dạng được đặt thành URL có giá trị là http://www.example.com/foo.html, thì chỉ dữ liệu của trang đó được trả về.

Kích thước

Phương diện xác định một nhóm dữ liệu cụ thể mà một bản ghi đang được tổng hợp, ví dụ: hệ số hình dạng PHONE cho biết bản ghi chứa thông tin về các lượt tải diễn ra trên thiết bị di động. Mỗi phương diện sẽ có một số giá trị nhất định và việc không chỉ định phương diện đó có nghĩa là phương diện đó được tổng hợp trên tất cả các giá trị. Ví dụ: việc không chỉ định kiểu dáng cho biết bản ghi chứa thông tin về các lượt tải diễn ra trên bất kỳ kiểu dáng nào.

Kiểu dáng

Loại thiết bị mà người dùng cuối đã sử dụng để chuyển đến trang. Đây là một lớp chung của thiết bị được chia thành PHONE, TABLET và DESKTOP.

Chỉ số

Chúng tôi báo cáo các chỉ số báo cáo dưới dạng tổng hợp thống kê, trong biểu đồ, phân vị và phân số.

Giá trị dấu phẩy động được làm tròn đến 4 chữ số thập phân (lưu ý rằng các chỉ số cumulative_layout_shift là số thực có độ chính xác gấp đôi được mã hoá dưới dạng chuỗi, vì vậy, không được coi là số thực và được báo cáo đến 2 chữ số thập phân trong chuỗi).

Biểu đồ

Khi các chỉ số được thể hiện dưới dạng biểu đồ tần suất, chúng tôi sẽ cho biết tỷ lệ phần trăm số lượt tải trang thuộc các phạm vi cụ thể cho chỉ số đó.

Biểu đồ tần suất ba nhóm cho một chỉ số mẫu sẽ có dạng như sau:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Dữ liệu này cho biết rằng đối với 38, 18% số lượt tải trang,chỉ số ví dụ được đo trong khoảng từ 0 mili giây đến 1.000 mili giây. Đơn vị của chỉ số không có trong biểu đồ này, trong trường hợp này, chúng ta sẽ giả định là mili giây.

Ngoài ra, 49,91% số lượt tải trang có giá trị chỉ số từ 1.000 mili giây đến 3.000 mili giây và 11,92% có giá trị lớn hơn 3.000 mili giây.

Phân vị

Các chỉ số cũng có thể chứa các phân vị hữu ích cho việc phân tích bổ sung. Chúng tôi báo cáo các giá trị chỉ số cụ thể ở phân vị đã cho của chỉ số đó. Các giá trị này dựa trên toàn bộ tập dữ liệu hiện có chứ không phải dữ liệu được phân nhóm cuối cùng, vì vậy, các giá trị này không nhất thiết phải khớp với phân vị nội suy dựa trên biểu đồ tần suất được phân nhóm cuối cùng.

{
  "percentiles": {
    "p75": 2063
  }
}

Trong ví dụ này, ít nhất 75% số lượt tải trang được đo lường bằng giá trị chỉ số <= 2063.

Phân số

Phân số cho biết tỷ lệ phần trăm lượt tải trang có thể được gắn nhãn theo một cách cụ thể. Trong trường hợp này, giá trị của chỉ số là các nhãn này.

Ví dụ: chỉ số form_factors bao gồm một đối tượng fractions liệt kê thông tin chi tiết về kiểu dáng (hoặc thiết bị) mà cụm từ tìm kiếm đã cho bao gồm:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

Trong trường hợp này, 3,77% lượt tải trang được đo lường trên máy tính, 2,88% trên máy tính bảng và 93,35% trên điện thoại, tổng cộng là 100%.

Các loại giá trị chỉ số

Mối liên kết giữa tên chỉ số BigQuery

Khoảng thời gian thu thập

Kể từ tháng 10 năm 2022, CrUX API chứa một đối tượng collectionPeriod có các trường firstDate và endDate đại diện cho ngày bắt đầu và ngày kết thúc của khoảng thời gian tổng hợp. Ví dụ:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Điều này giúp bạn hiểu rõ hơn về dữ liệu và biết liệu dữ liệu đã được cập nhật cho ngày hôm đó hay chưa hoặc có đang trả về dữ liệu giống như ngày hôm qua hay không.

Bạn cũng có thể xem khoảng thời gian thu thập dữ liệu trong PageSpeed Insights:

Ngoài ra, collectionPeriod sẽ luôn hiển thị 28 ngày, ngay cả khi dữ liệu không phải là của 28 ngày đầy đủ (ví dụ: nếu một trang được ra mắt chưa đầy 28 ngày trước). collectionPeriod là khoảng thời gian mà dữ liệu CrUX được tổng hợp, không nhất thiết là khoảng thời gian mà dữ liệu đại diện.

Câu hỏi mẫu

Các truy vấn được gửi dưới dạng đối tượng JSON bằng cách sử dụng yêu cầu POST đến https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" với dữ liệu truy vấn dưới dạng đối tượng JSON trong phần nội dung POST:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Ví dụ: bạn có thể gọi lệnh này từ curl bằng dòng lệnh sau (thay thế API_KEY bằng khoá của bạn):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

Dữ liệu ở cấp trang có sẵn thông qua API bằng cách truyền thuộc tính url trong truy vấn, thay vì origin:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Nếu bạn không đặt thuộc tính metrics, thì tất cả các chỉ số có sẵn sẽ được trả về:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (chỉ được báo cáo nếu không có formFactor nào được chỉ định trong yêu cầu)
• experimental_ad_count (chỉ được báo cáo cho các trang có trong chỉ số quảng cáo)
• experimental_ad_density (chỉ được báo cáo cho các trang có trong chỉ số quảng cáo)
• experimental_ad_cpu (chỉ được báo cáo cho những trang có trong chỉ số quảng cáo)
• experimental_ad_kilobytes (chỉ được báo cáo cho những trang có trong chỉ số quảng cáo)

Nếu bạn không cung cấp giá trị formFactor, thì các giá trị sẽ được tổng hợp trên tất cả các hệ số hình dạng.

Hãy xem bài viết Sử dụng API Báo cáo trải nghiệm người dùng trên Chrome để biết thêm các truy vấn mẫu.

Quy trình dữ liệu

Tập dữ liệu CrUX được xử lý thông qua một quy trình để hợp nhất, tổng hợp và lọc dữ liệu trước khi có thể sử dụng thông qua API.

Trung bình luân phiên

Dữ liệu trong Báo cáo trải nghiệm người dùng trên Chrome là giá trị trung bình luân phiên trong 28 ngày của các chỉ số tổng hợp. Điều này có nghĩa là dữ liệu được trình bày trong Báo cáo trải nghiệm người dùng trên Chrome tại bất kỳ thời điểm nào thực sự là dữ liệu tổng hợp trong 28 ngày qua.

Điều này tương tự như cách tập dữ liệu CrUX trên BigQuery tổng hợp các báo cáo hằng tháng.

Cập nhật hằng ngày

Dữ liệu được cập nhật hằng ngày vào khoảng 4:00 giờ UTC. Không có thoả thuận mức độ cung cấp dịch vụ nào về thời gian cập nhật; việc này được thực hiện hằng ngày trên cơ sở nỗ lực tối đa.

Lược đồ

CrUX API có một điểm cuối duy nhất chấp nhận các yêu cầu HTTP POST. API này trả về một record chứa một hoặc nhiều metrics tương ứng với dữ liệu hiệu suất về nguồn gốc hoặc trang được yêu cầu.

Yêu cầu HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

URL sử dụng cú pháp Chuyển mã gRPC.

Nội dung yêu cầu

Nội dung yêu cầu phải chứa dữ liệu có cấu trúc sau:

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

Ví dụ: để yêu cầu giá trị nội dung lớn nhất hiển thị trên máy tính cho trang chủ của tài liệu dành cho nhà phát triển Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Nội dung phản hồi

Các yêu cầu thành công sẽ trả về phản hồi bằng đối tượng record và urlNormalizationDetails theo cấu trúc sau:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Ví dụ: phản hồi cho nội dung yêu cầu trong yêu cầu trước đó có thể là:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Khoá

Key xác định tất cả các phương diện giúp xác định bản ghi này là duy nhất.

{
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

Chỉ số

metric là một tập hợp dữ liệu tổng hợp về trải nghiệm người dùng cho một chỉ số hiệu suất duy nhất của trang web, chẳng hạn như nội dung đầu tiên hiển thị. Báo cáo này có thể chứa biểu đồ tóm tắt về mức sử dụng Chrome trong thực tế dưới dạng một loạt bins, dữ liệu phân vị cụ thể (chẳng hạn như p75) hoặc có thể chứa các phân số được gắn nhãn.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

hoặc

{
  "fractions": {
    object (Fractions)
  }
}

Thùng

bin là một phần dữ liệu riêng biệt kéo dài từ đầu đến cuối hoặc nếu không có điểm kết thúc thì kéo dài từ đầu đến vô cực dương.

Giá trị bắt đầu và kết thúc của một nhóm được cung cấp theo loại giá trị của chỉ số mà nhóm đó đại diện. Ví dụ: nội dung đầu tiên hiển thị được đo bằng mili giây và hiển thị dưới dạng số nguyên, do đó, các nhóm chỉ số của nội dung này sẽ sử dụng int32 cho các loại bắt đầu và kết thúc. Tuy nhiên, mức thay đổi bố cục tích luỹ được đo bằng số thập phân không có đơn vị và được hiển thị dưới dạng số thập phân được mã hoá dưới dạng chuỗi, do đó, các nhóm chỉ số của chỉ số này sẽ sử dụng chuỗi cho loại giá trị.

{
  "start": value,
  "end": value,
  "density": number
}

Phân vị

Percentiles chứa các giá trị tổng hợp của một chỉ số ở một phân vị thống kê nhất định. Các chỉ số này được dùng để ước tính giá trị của một chỉ số mà một tỷ lệ phần trăm người dùng trải nghiệm trong tổng số người dùng.

{
  "P75": value
}

Phân số

Fractions chứa các phân số được gắn nhãn có tổng bằng ~1. Mỗi nhãn mô tả một cách nào đó về lượt tải trang, vì vậy, bạn có thể coi các chỉ số được biểu thị theo cách này là tạo ra các giá trị riêng biệt thay vì giá trị bằng số và các phân số thể hiện tần suất đo lường một giá trị riêng biệt cụ thể.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Tương tự như các giá trị mật độ trong các nhóm biểu đồ, mỗi fraction là một số 0.0 <= value <= 1.0 và tổng của chúng là ~1.0.

UrlNormalization

Đối tượng đại diện cho các hành động chuẩn hoá được thực hiện để chuẩn hoá một URL nhằm tăng khả năng tra cứu thành công. Đây là những thay đổi cơ bản, tự động được thực hiện khi tra cứu url_pattern được cung cấp sẽ không thành công. Các thao tác phức tạp như theo dõi lệnh chuyển hướng sẽ không được xử lý.

{
  "originalUrl": string,
  "normalizedUrl": string
}

Giới hạn số lượng yêu cầu

CrUX API được giới hạn ở mức 150 truy vấn mỗi phút cho mỗi dự án Google Cloud và được cung cấp miễn phí. Bạn có thể xem hạn mức này và mức sử dụng hiện tại của mình trong Bảng điều khiển Google Cloud. Hạn mức này đủ cho phần lớn các trường hợp sử dụng và bạn không thể trả phí để tăng hạn mức.