API CrUX

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

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

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

Khoá API CrUX

Bạn phải có khoá Google Cloud API để sử dụng CrUX API. Bạn có thể tạo mã này trong trang Thông tin xác thực và cung cấp mã này để sử dụng Chrome UX Report API.

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

Khoá API an toàn để nhúng trong URL và không cần sử dụng phương thức mã hoá nào.

Mô hình dữ liệu

Phần này trình bày chi tiết cấu trúc của dữ liệu trong 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ể chứa dữ liệu cụ thể cho một giá trị nhận dạng và cho một tổ hợp cụ thể của các phương diện. Một bản ghi có thể chứa dữ liệu của một hoặc nhiều chỉ số.

Giá trị nhận dạng

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

Điểm gốc

Khi giá trị nhận dạng là một nguồn gốc, thì mọi dữ liệu hiện có cho tất cả các trang thuộc nguồn gốc đó sẽ được tổng hợp 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 này:

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 có 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ề và tổng hợp với nhau vì đó là tất cả các trang thuộc nguồn gốc đó.

URL

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

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

Nếu mã nhận dạng được đặt thành URL có giá trị là http://www.example.com/foo.html, thì chỉ có dữ liệu cho 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ụ như hệ số hình dạng PHONE cho biết bản ghi chứa thông tin về những lần tải diễn ra trên thiết bị di động. Mỗi phương diện sẽ có một số lượng giá trị nhất định, và việc thiếu chỉ định phương diện đó sẽ ngầm ẩn rằng phương diện được tổng hợp trên tất cả các giá trị. Ví dụ: việc chỉ định không có hệ số hình dạng nào cho biết rằng bản ghi đó chứa thông tin về những lần tải diễn ra trên bất kỳ hệ số hình dạng nào.

Kiểu dáng

Lớp 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.

Loại kết nối hiệu quả

Loại kết nối hiệu quả là chất lượng kết nối ước tính của thiết bị khi chuyển đến trang. Đây là một lớp chung được chia thành offline, slow-2G, 2G, 3G và 4G.

Chỉ số

Chúng tôi báo cáo các chỉ số dưới dạng dữ liệu 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 chỉ số cumulative_layout_shift được mã hoá kép 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 biểu thị trong biểu đồ, chúng tôi sẽ hiển thị tỷ lệ phần trăm số lượt tải trang thuộc phạm vi cụ thể cho chỉ số đó.

Một biểu đồ ba thùng đơn giản cho một chỉ số mẫu 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 thấy rằng đối với 38, 18% lượt tải trang,chỉ số mẫu được đo trong khoảng từ 0 mili giây đến 1.000 mili giây. Các đơn vị của chỉ số không có trong biểu đồ này, trong trường hợp này, chúng tôi sẽ giả định là mili giây.

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

Phân vị

Các chỉ số cũng có thể chứa phân vị có thể hữu ích cho việc phân tích bổ sung. Chúng tôi báo cáo các giá trị của chỉ số cụ thể tại phân vị đã cho cho chỉ số đó. Các biểu đồ này dựa trên tập dữ liệu đầy đủ có sẵn chứ không phải dữ liệu gộp cuối cùng, vì vậy, các mô hình 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 đồ được liên kết cuối cùng.

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

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

Phân số

Các phân số cho biết tỷ lệ phần trăm số lượt tải trang có thể được gắn nhãn theo cách cụ thể. Trong trường hợp này, giá trị 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ề các hệ số hình dạng (hoặc thiết bị) mà truy vấn nhất định đề cập:

"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 trên máy tính để bàn, 2,88% trên máy tính bảng và 93,35% trên điện thoại, tổng số là 100%.

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

Tên chỉ số API CrUX Loại dữ liệu Đơn vị hệ mét Tổng hợp thống kê Tài liệu
cumulative_layout_shift 2 chữ số thập phân kép được mã hoá dưới dạng chuỗi không đơn vị biểu đồ có 3 thùng, phân vị có p75 cls
first_contentful_paint int mili giây biểu đồ có 3 thùng, phân vị có p75 fcp
first_input_delay
(không dùng nữa)		 int mili giây biểu đồ có 3 thùng, phân vị có p75 id
interaction_to_next_paint int mili giây biểu đồ có 3 thùng, phân vị có p75 inp
largest_contentful_paint int mili giây biểu đồ có 3 thùng, phân vị có p75 lcp
experimental_time_to_first_byte int mili giây biểu đồ có 3 thùng, phân vị có p75 ttfb
form_factors Dấu hai chấm thập phân dấu phần trăm liên kết từ kiểu dáng đến phân số kiểu dáng
navigation_types Dấu hai chấm thập phân dấu phần trăm ánh xạ từ loại điều hướng đến phân số các loại điều hướng
round_trip_time int mili giây phân vị có p75 rtt

Liên kết tên chỉ số BigQuery

Tên chỉ số API CrUX Tên chỉ số BigQuery
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
first_input_delay first_input.delay
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
navigation_types navigation_types
form_factors không áp dụng
round_trip_time không áp dụng

Kỳ 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 biểu thị ngày bắt đầu và ngày kết thúc của cửa sổ tổng hợp. Ví dụ:

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

Việc này giúp bạn hiểu rõ hơn về dữ liệu và xác định xem liệu dữ liệu đã được cập nhật cho ngày đó hay đang trả về dữ liệu giống như ngày hôm qua.

Xin lưu ý rằng CrUX API chậm hơn ngày hôm nay khoảng hai ngày vì API này chờ dữ liệu hoàn chỉnh trong ngày và cần một khoảng thời gian xử lý trước khi API đó xuất hiện trong API. Múi giờ được sử dụng là Giờ chuẩn Thái Bình Dương (PST) và không thay đổi giờ mùa hè.

Cụm từ tìm kiếm 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 tới 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 chuyển thuộc tính url vào 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
  • first_input_delay (không dùng nữa)
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (chỉ được báo cáo nếu không formFactor nào được chỉ định trong yêu cầu)

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ả 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 cung cấp bằng 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à số liệu trung bình luân phiên trong 28 ngày của các chỉ số tổng hợp. Tức 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 một thời điểm bất kỳ thực ra là dữ liệu trong 28 ngày qua được tổng hợp lại với nhau.

Đ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.

Thông tin cập nhật hằng ngày

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

Lược đồ

Có một điểm cuối duy nhất cho API CrUX chấp nhận các yêu cầu HTTP POST. API 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 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 như sau:

{
  "effectiveConnectionType": string,
  "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.
}
Trường
effectiveConnectionType

string

Loại kết nối hiệu quả là phương diện truy vấn chỉ định lớp mạng hiệu quả chứa dữ liệu của bản ghi.

Trường này sử dụng các giá trị ["offline", "slow-2G", "2G", "3G", "4G"] như được chỉ định trong thông số kỹ thuật của Network Information API

Lưu ý: Nếu không có loại kết nối hiệu quả nào được chỉ định, thì hệ thống sẽ trả về bản ghi đặc biệt có dữ liệu tổng hợp về tất cả các loại kết nối hiệu quả.
formFactor

enum (FormFactor)

Hệ số hình dạng là phương diện truy vấn chỉ định lớp thiết bị chứa dữ liệu của bản ghi.

Trường này sử dụng các giá trị DESKTOP, PHONE hoặc TABLET.

Lưu ý: Nếu bạn không chỉ định hệ số hình dạng nào, thì hệ thống sẽ trả về bản ghi đặc biệt chứa dữ liệu tổng hợp cho tất cả các hệ số hình dạng.
metrics[]

string

Các chỉ số cần được đưa vào câu trả lời. Nếu bạn không chỉ định chỉ số nào, thì hệ thống sẽ trả về mọi chỉ số tìm được.

Giá trị được phép: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Trường kết hợp url_pattern. url_pattern là giá trị nhận dạng chính để tra cứu bản ghi. Đó chỉ có thể là một trong những trạng thái sau:
origin

string

"Nguồn gốc" url_pattern cho biết mẫu URL là nguồn gốc của một trang web.

Ví dụ: "https://example.com", "https://cloud.google.com"
url

string

url_pattern url đề cập đến mẫu URL là bất kỳ URL tuỳ ý nào.

Ví dụ: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Ví dụ: để yêu cầu giá trị hiển thị nội dung lớn nhất trên máy tính cho trang chủ 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ề các phản hồi có đối tượng record và urlNormalizationDetails trong 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 định nghĩa mọi phương diện xác định bản ghi này là duy nhất.

{
  "effectiveConnectionType": string,
  "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.
}
Trường
formFactor

enum (FormFactor)

Kiểu dáng là loại thiết bị mà tất cả người dùng dùng để truy cập vào trang web cho bản ghi này.

Nếu bạn chưa chỉ định hệ số hình dạng này, thì dữ liệu tổng hợp cho tất cả các hệ số hình dạng sẽ được trả về.
effectiveConnectionType

string

Loại kết nối hiệu quả là lớp kết nối chung mà tất cả người dùng đều gặp phải đối với bản ghi này. Trường này sử dụng các giá trị ["offline", "slow-2G", "2G", "3G", "4G"] như được nêu trong: https://wicg.github.io/netinfo/#effective-connection-types

Nếu loại kết nối hiệu quả không được chỉ định, thì dữ liệu tổng hợp về tất cả các loại kết nối hiệu quả sẽ được trả về.
Trường kết hợp url_pattern. Mẫu URL là URL áp dụng bản ghi. url_pattern chỉ có thể là một trong những trạng thái sau đây:
origin

string

origin chỉ định nguồn gốc của bản ghi này.

Lưu ý: Khi bạn chỉ định origin, dữ liệu cho các lượt tải theo nguồn gốc này trên tất cả các trang sẽ được tổng hợp thành dữ liệu về trải nghiệm người dùng ở cấp độ gốc.
url

string

url chỉ định một URL cụ thể chứa bản ghi này.

Lưu ý: Khi bạn chỉ định một url, dữ liệu chỉ được tổng hợp cho URL cụ thể đó.

Chỉ số

metric là tậ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 web, chẳng hạn như nội dung đầu tiên hiển thị. Tệp này có thể chứa biểu đồ tóm tắt về việc sử dụng Chrome trong thực tế dưới dạng một chuỗi 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)
  }
}
Trường
histogram[]

object (Bin)

Biểu đồ trải nghiệm người dùng cho một chỉ số. Biểu đồ này sẽ có ít nhất một thùng và mật độ của tất cả các thùng sẽ cộng lại tối đa là ~1.
percentiles

object (Percentiles)

Phân vị hữu ích phổ biến của Chỉ số. Loại giá trị cho phân vị sẽ giống với loại giá trị được cung cấp cho các thùng Biểu đồ.
fractions

object (Fractions)

Đối tượng này chứa các phân số được gắn nhãn, có tổng bằng ~1.

Phân số được làm tròn đến 4 chữ số thập phân.

Khoảng giá trị

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 nào được gán từ đầu đến vô hạn dương.

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

{
  "start": value,
  "end": value,
  "density": number
}
Trường
start

(integer | string)

Bắt đầu là điểm bắt đầu của thùng dữ liệu.
end

(integer | string)

Đây là điểm kết thúc của thùng dữ liệu. Nếu điểm cuối không được điền, thì thùng rác sẽ không có điểm kết thúc và có hiệu lực từ đầu đến +inf.
density

number

Tỷ lệ người dùng thấy giá trị của thùng này cho chỉ số nhất định.

Mật độ được làm tròn đến 4 chữ số thập phân.

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 dùng để ước tính giá trị của một chỉ số theo trải nghiệm của một tỷ lệ phần trăm người dùng trên tổng số người dùng.

{
  "P75": value
}
Trường
p75

(integer | string)

75% lượt tải trang gặp phải chỉ số nhất định bằng hoặc thấp hơn giá trị này.

Phân số

Fractions chứa các phân số có nhãn, có tổng bằng ~1. Mỗi nhãn mô tả lượt tải trang theo một cách nào đó, 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ị số. Đồng thời, 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
}

Giống như các giá trị mật độ trong thùng biểu đồ, mỗi fraction là một số 0.0 <= value <= 1.0 và cộng lại thành ~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 được khả năng tra cứu thành công cao hơn. Đây là những thay đổi tự động đơn giản được thực hiện khi tra cứu url_pattern được cung cấp sẽ được xác định là không thành công. Các thao tác phức tạp như chuyển hướng sau đây sẽ không được xử lý.

{
  "originalUrl": string,
  "normalizedUrl": string
}
Trường
originalUrl

string

URL được yêu cầu ban đầu trước khi có bất kỳ hành động chuẩn hoá nào.
normalizedUrl

string

URL sau khi có hành động chuẩn hoá. Đây là URL trải nghiệm người dùng hợp lệ và có thể được tra cứu một cách hợp lý.

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

API CrUX bị 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 Google Cloud Console. Hạn mức hào phóng này sẽ đủ cho phần lớn các trường hợp sử dụng và sẽ không thể chi trả cho hạn mức tăng.