CrUX API 能讓您低延遲存取網頁和來源精細程度的匯總即時使用者體驗資料,
常見用途
CrUX API 可用來查詢特定 URI 的使用者體驗指標,例如「取得 https://example.com
來源的指標」。
CrUX API 金鑰
您必須有 Google Cloud API 金鑰,才能使用 CrUX API。您可以在「憑證」頁面中建立一個,並佈建 Chrome UX Report API
以供使用。
取得 API 金鑰後,應用程式可將查詢參數 key=[YOUR_API_KEY]
附加到所有要求網址。請參閱查詢範例。
API 金鑰可以安全地嵌入網址中,不需任何編碼。
資料模型
本節將詳細說明要求和回應中的資料結構。
錄音
網頁或網站的個別資訊。記錄可能包含專屬 ID 和特定維度組合的資料。記錄可包含一或多個指標的資料,
ID
ID 會指定應查詢的記錄。在 CrUX 中,這些 ID 是網頁和網站。
來源
如果 ID 是來源,系統會將該來源中所有網頁的資料匯總在一起。舉例來說,假設 http://www.example.com
來源含有以下 Sitemap 所配置的網頁:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
也就是說,查詢來源設為 http://www.example.com
的 Chrome 使用者體驗報告時,系統會將 http://www.example.com/
、http://www.example.com/foo.html
和 http://www.example.com/bar.html
的資料匯總在一起,因為這些網頁都是該來源下的所有網頁。
網址
如果 ID 是網址,系統只會傳回該網址的資料。再次查看 http://www.example.com
來源 Sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
如果 ID 設為的網址值為 http://www.example.com/foo.html
,系統只會傳回該網頁的資料。
尺寸
維度會辨識記錄正在匯總的特定資料群組。舉例來說,PHONE
的板型規格表示記錄包含行動裝置載入情形的相關資訊。每個維度的值數量都不相同,但如果沒有指定該維度,就表示維度會匯總所有值。舉例來說,如果不指定板型規格,表示記錄含有任何板型規格的載入資訊。
板型規格
使用者用來前往該頁面的裝置類別。這是裝置的一般類別,分為 PHONE
、TABLET
和 DESKTOP
。
有效的連線類型
「有效連線類型」是瀏覽頁面時裝置的預估連線品質。一般類別分為 offline
、slow-2G
、2G
、3G
和 4G
。
指標
我們會以統計匯總、直方圖、百分位數和分數的形式回報指標。
浮點值會四捨五入至小數點後 4 位 (請注意,cumulative_layout_shift
指標會雙倍編碼為字串,因此不會考慮浮點值,且會回報為字串中的小數點後 2 位)。
直方圖
在直方圖中呈現指標時,我們會顯示網頁載入百分比落在該指標的特定範圍內。
簡易指標範例的三個特徵分塊直方圖如下所示:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
這項資料顯示,在網頁載入的時間佔 38.18%,範例指標的測量時間為 0 毫秒到 1,000 毫秒。這個直方圖不包含指標的單位,在本例中,我們是以毫秒為單位。
此外,有 49.91% 的網頁載入看到介於 1,000 毫秒到 3,000 毫秒之間的指標值,而 11.92% 的值超過 3,000 毫秒。
百分排名
指標也可能包含百分位數,可用於進一步分析。 系統會在該指標的指定百分位數顯示特定指標值。這些物件是以完整的可用資料組合 (而非最終繫結資料) 為基礎,因此不一定能符合以最終繫結直方圖為基礎的內插百分位數。
{
"percentiles": {
"p75": 2063
}
}
在本例中,至少有 75% 的網頁載入是以指標值 <= 2063
進行測量。
分數
分數代表可透過特定方式加上標籤的網頁載入百分比。 在這種情況下,指標值就是這些標籤。
舉例來說,form_factors
指標包含 fractions
物件,其中列出特定查詢涵蓋的板型規格 (或裝置) 細目:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
在本例中,3.77% 的網頁載入是在桌機上測得的,在平板電腦上的佔比為 2.88%,手機佔 93.35%,總計 100%。
指標值類型
CrUX API 指標名稱 | 資料類型 | 公制單位 | 統計匯總 | 說明文件 |
---|---|---|---|---|
cumulative_layout_shift |
2 個小數點後雙重編碼,以字串表示 | 無單位 | 有三個特徵分塊的直方圖,第 75 個百分位數 | cls |
first_contentful_paint |
int | 毫秒 | 有三個特徵分塊的直方圖,第 75 個百分位數 | fcp |
first_input_delay (已淘汰) |
int | 毫秒 | 有三個特徵分塊的直方圖,第 75 個百分位數 | 汽車 |
interaction_to_next_paint |
int | 毫秒 | 有三個特徵分塊的直方圖,第 75 個百分位數 | 英寸 |
largest_contentful_paint |
int | 毫秒 | 有三個特徵分塊的直方圖,第 75 個百分位數 | lcp |
experimental_time_to_first_byte |
int | 毫秒 | 有三個特徵分塊的直方圖,第 75 個百分位數 | Ttfb |
form_factors |
4 位小數 (雙位數) | 百分比 | 從板型規格對應至分數 | 板型規格 |
navigation_types |
4 位小數 (雙位數) | 百分比 | 從導覽類型對應至分數 | 導覽類型 |
BigQuery 指標名稱對應
CrUX API 指標名稱 | 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 |
n/a |
收集期間
自 2022 年 10 月起,CrUX API 包含 collectionPeriod
物件,且包含 firstDate
和 endDate
欄位,代表匯總期間的開始和結束日期。例如:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
如此一來,您就能更加瞭解資料,以及該日期是否已經更新,或傳回的資料與昨天相同。
請注意,CrUX API 會等待當天完成的資料,並需要經過一段時間的處理時間,才能在 API 中顯示,因此約比今天日期晚兩天左右。採用的時區為太平洋標準時間 (PST),不會變更日光節約時間。
查詢範例
查詢會以 JSON 物件的形式提交,向 https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
發出 POST 要求,並將查詢資料做為 POST 主體中的 JSON 物件:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
舉例來說,您可以透過下列指令列從 curl
呼叫此方法 (將 API_KEY
換成您的金鑰):
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"]}'
如要透過 API 取得網頁層級資料,請在查詢中傳遞 url
屬性 (而非 origin
):
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
如未設定 metrics
屬性,系統會傳回所有可用的指標:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(已淘汰)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(只有在要求中未指定formFactor
時才會回報)
如未提供 formFactor
值,系統會匯總所有板型規格的值。
如需更多查詢範例,請參閱使用 Chrome UX Report API。
資料管道
CrUX 資料集會透過管道處理,以整合、匯總及篩選資料,再將資料提供給 API。
累計平均
Chrome 使用者體驗報告中的資料是匯總指標 28 天的累計平均值。換句話說,Chrome 使用者體驗報告在任何特定時間點顯示的資料,實際上都是過去 28 天的資料匯總結果。
這與 BigQuery 的 CrUX 資料集匯總每月報表的方式類似。
每日更新
資料會在每天世界標準時間 04:00 左右更新。Google 並未提供確切的更新時間服務水準協議。這項協議每天會盡力而為。
結構定義
CrUX API 有單一端點,可用於接受 POST
HTTP 要求。API 會傳回 record
,其中包含一或多個對應所要求來源或網頁成效資料的 metrics
。
HTTP 要求
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體應包含結構如下的資料:
{
"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.
}
欄位 | |
---|---|
effectiveConnectionType |
有效連線類型是一種查詢維度,用於指定記錄資料所屬的有效網路類別。 此欄位使用 Network Information API 規格中指定的值 注意: 如果沒有指定有效連線類型,系統會傳回包含所有有效連線類型之匯總資料的特殊記錄。 |
formFactor |
板型規格是一種查詢維度,用於指定記錄資料所屬的裝置類別。 這個欄位使用 注意:如未指定板型規格,系統會傳回含有所有板型規格匯總資料的特殊記錄。 |
metrics[] |
回應中應包含的指標。如未指定,系統會傳回任何找到的指標。 允許的值: |
聯集欄位 url_ 。url_pattern 是記錄查詢的主要 ID。只能採用下列其中一種設定: |
|
origin |
範例: |
url |
範例: |
舉例來說,如要要求 Chrome 開發人員說明文件首頁最大的電腦版內容繪製值,請按照下列步驟操作:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
回應主體
成功的要求會傳回具備 record
物件和 urlNormalizationDetails
的回應,結構如下:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
例如,對先前要求中要求主體的回應如下:
{
"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
}
}
}
}
鍵
Key
會將辨識這筆記錄視為不重複的所有維度。
{
"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.
}
欄位 | |
---|---|
formFactor |
板型規格是指所有使用者用來存取網站的裝置類別。 如未指定板型規格,系統會傳回所有板型規格的匯總資料。 |
effectiveConnectionType |
有效的連線類型是所有使用者對這項記錄體驗的一般連線類別。這個欄位使用 ["Offline", "slow-2G", "2G", "3G", "4G"] 的值,如 https://wicg.github.io/netinfo/#effective-connection-types 指定。 如未指定有效連線類型,系統會傳回所有有效連線類型的匯總資料。 |
聯集欄位 url_ 。網址模式是指該記錄要套用的網址。url_ 只能是下列其中一項: |
|
origin |
注意:指定 |
url |
注意:僅指定 |
指標
metric
是單一網路成效指標 (例如首次顯示內容所需時間) 的匯總使用者體驗資料,這可能包含一系列 bins
、特定百分位數資料 (例如 p75) 的摘要直方圖,或含有已加上標籤的分數。
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
或
{
"fractions": {
object (Fractions)
}
}
欄位 | |
---|---|
histogram[] |
指標使用者體驗的直方圖。直方圖至少會有一個特徵分塊,所有特徵的密度總和等於約 1。 |
percentiles |
指標的常見實用百分位數。百分位數的值類型會與直方圖特徵分塊的值類型相同。 |
fractions |
這個物件包含已加上標籤的分數,總和為 1。 分數會四捨五入至小數點後 4 位。 |
特徵分塊
bin
是資料從開始到結束的獨立部分,或若沒有結束,則從開始到正無限大。
特徵代表的起始值和結束值會以其所代表指標的值類型提供。舉例來說,首次顯示內容所需時間的測量單位是毫秒,然後暴露為 int 值,因此指標特徵集將使用 int32s 作為起始和結束類型。不過,累計版面配置位移是以無單位小數測量,並以十進位編碼的形式呈現,因此指標特徵的值類型會使用字串做為值類型。
{
"start": value,
"end": value,
"density": number
}
欄位 | |
---|---|
start |
「開始」是資料特徵分塊的起點, |
end |
「結束」為資料特徵分塊的結尾。如果未填入結尾,特徵分塊就不會結束,且有效時間從起點到 +inf。 |
density |
受這個特徵分塊針對特定指標值的使用者比例。 密度會四捨五入至小數點後 4 位。 |
百分排名
Percentiles
包含指定統計百分位數的指標綜合值。用於估算從使用者總人數中,特定百分比的使用者所體驗到的指標值。
{
"P75": value
}
欄位 | |
---|---|
p75 |
75% 的網頁載入時間達到指定指標值或小於這個值。 |
分數
Fractions
包含已加上標籤的分數,總和為 1。每個標籤都以某種方式描述網頁載入,因此以這種方式呈現的指標可視為產生不同的值 (而非數值),而分數代表了特定不同值的測量頻率。
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
與直方圖特徵中的密度值非常類似,每個 fraction
都是數字 0.0 <= value <= 1.0
,且總和等於約 1.0。
UrlNormalization
這個物件代表將網址正規化時採取的正規化操作,以便提高查詢成功的機率。這些簡單的自動變更,會在查詢提供的 url_pattern
時執行。系統不會處理下列重新導向等複雜動作。
{
"originalUrl": string,
"normalizedUrl": string
}
欄位 | |
---|---|
originalUrl |
在任何正規化動作之前要求的原始網址。 |
normalizedUrl |
任何正規化動作後的網址。這是可合理查詢的有效使用者體驗網址。 |
頻率限制
對於每項 Google Cloud 專案,CrUX API 每分鐘最多只能執行 150 次查詢,而且無須付費。您可以在 Google Cloud 控制台中查看這項限制和目前的用量。這個大量配額應足以因應大多數用途的需求,而且無法針對增加的配額付費。