เรียนรู้วิธีใช้ Chrome UX Report API เพื่อเข้าถึงข้อมูลประสบการณ์ของผู้ใช้จริงจากหลายล้านเว็บไซต์
ชุดข้อมูลรายงาน UX ของ Chrome (CrUX) แสดงถึงประสบการณ์จริงของผู้ใช้ Chrome ในการใช้งานปลายทางยอดนิยมในเว็บ ตั้งแต่ปี 2017 เมื่อมีการเปิดตัวชุดข้อมูลที่ค้นหาได้ใน BigQuery เป็นครั้งแรก เราได้ผสานรวมข้อมูลภาคสนามจาก CrUX ไว้ในเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ เช่น PageSpeed Insights, แดชบอร์ด CrUX และรายงาน Core Web Vitals ของ Search Console ซึ่งช่วยให้นักพัฒนาซอฟต์แวร์วัดและตรวจสอบประสบการณ์ของผู้ใช้จริงได้ สิ่งที่หายไปตลอดมาคือเครื่องมือที่ให้สิทธิ์เข้าถึงข้อมูล CrUX แบบเป็นโปรแกรมได้โดยไม่มีค่าใช้จ่ายและ RESTful เรายินดีที่จะประกาศการเปิดตัว Chrome UX Report API ใหม่ทั้งหมด เพื่อช่วยเติมเต็มช่องว่างนั้น
API นี้สร้างขึ้นโดยมีเป้าหมายเพื่อให้นักพัฒนาแอปเข้าถึงข้อมูล CrUX ได้อย่างง่ายดาย รวดเร็ว และครอบคลุม CrUX API จะรายงานเฉพาะข้อมูลประสบการณ์ของผู้ใช้ในภาคสนาม ซึ่งต่างจาก PageSpeed Insights API ที่มีอยู่ซึ่งจะรายงานข้อมูล lab จากการตรวจสอบประสิทธิภาพของ Lighthouse ด้วย CrUX API ได้รับการปรับปรุงให้มีประสิทธิภาพและสามารถแสดงข้อมูลประสบการณ์ของผู้ใช้ได้อย่างรวดเร็ว จึงเหมาะอย่างยิ่งสำหรับแอปพลิเคชันการตรวจสอบแบบเรียลไทม์
CrUX API จะตรวจสอบและตรวจสอบ Largest Contentful Paint (LCP), First Input Delay (FID) และ Cumulative Layout Shift (CLS) ทั้งในระดับต้นทางและระดับ URL เพื่อให้นักพัฒนาซอฟต์แวร์เข้าถึงเมตริกทั้งหมดที่สำคัญมากที่สุดได้
เรามาเจาะลึกและดูวิธีการใช้งานกันเลย
ข้อมูลต้นทางของการค้นหา
ต้นทางในชุดข้อมูล CrUX ครอบคลุมประสบการณ์ระดับหน้าเว็บทั้งหมดที่เกี่ยวข้อง ตัวอย่างต่อไปนี้แสดงวิธีค้นหาข้อมูลประสบการณ์ของผู้ใช้จากต้นทางใน CrUX API โดยใช้ cURL ในบรรทัดคำสั่ง
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"}'
คำสั่ง curl
ประกอบด้วย 3 ส่วน ดังนี้
- ปลายทาง URL ของ API รวมถึงคีย์ API ส่วนตัวของผู้โทร
- ส่วนหัว
Content-Type: application/json
ซึ่งบ่งชี้ว่าเนื้อหาของคำขอมี JSON - เนื้อหาของคำขอที่เข้ารหัส JSON ซึ่งระบุต้นทาง
https://web.dev
หากต้องการทำสิ่งเดียวกันนี้ใน JavaScript ให้ใช้ยูทิลิตี CrUXApiUtil
ซึ่งทำให้มีการเรียก API และแสดงผลการตอบสนองที่ถอดรหัสแล้ว (ดูตัวแปร GitHub เพิ่มเติม
เพื่อดูฟีเจอร์เพิ่มเติม รวมถึงประวัติและการสนับสนุนแบบกลุ่ม)
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;
});
};
แทนที่ [YOUR_API_KEY]
ด้วยคีย์ของคุณ ถัดไป ให้เรียกฟังก์ชัน CrUXApiUtil.query
แล้วส่งผ่านออบเจ็กต์เนื้อความ
CrUXApiUtil.query({
origin: 'https://web.dev'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
หากมีข้อมูลสำหรับต้นทางนี้ การตอบกลับของ API จะเป็นออบเจ็กต์ที่เข้ารหัส JSON ที่มีเมตริกที่แสดงถึงการกระจายประสบการณ์ของผู้ใช้ เมตริกการกระจายคือถังฮิสโตแกรมและเปอร์เซ็นไทล์
{
"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
}
},
// ...
}
}
}
พร็อพเพอร์ตี้ start
และ end
ของออบเจ็กต์ histogram
แสดงช่วงของค่าที่ผู้ใช้ได้รับสำหรับเมตริกที่ระบุ พร็อพเพอร์ตี้ density
แสดงสัดส่วนของประสบการณ์ของผู้ใช้ภายในช่วงนั้น ในตัวอย่างนี้ 79% ของประสบการณ์ของผู้ใช้ LCP ในหน้า web.dev ทั้งหมดใช้เวลาน้อยกว่า 2,500 มิลลิวินาที ซึ่งถือว่า "ดี" เกณฑ์ LCP ค่า percentiles.p75
หมายความว่า 75% ของประสบการณ์ของผู้ใช้ในการกระจายนี้มีค่าน้อยกว่า 2,216 มิลลิวินาที ดูข้อมูลเพิ่มเติมเกี่ยวกับโครงสร้างการตอบกลับในเอกสารเนื้อหาการตอบกลับ
ข้อผิดพลาด
เมื่อ CrUX API ไม่มีข้อมูลสําหรับต้นทางหนึ่งๆ ต้นทางจะตอบกลับด้วยข้อความแสดงข้อผิดพลาดที่เข้ารหัส JSON ดังนี้
{
"error": {
"code": 404,
"message": "chrome ux report data not found",
"status": "NOT_FOUND"
}
}
หากต้องการแก้ไขข้อบกพร่องของข้อผิดพลาดนี้ ให้ตรวจสอบว่าต้นทางที่ขอนำทางได้แบบสาธารณะหรือไม่ ซึ่งทดสอบได้โดยการป้อนต้นทางลงในแถบที่อยู่ของเบราว์เซอร์และเปรียบเทียบกับ URL สุดท้ายหลังจากที่มีการเปลี่ยนเส้นทาง ปัญหาที่พบบ่อย ได้แก่ การเพิ่มหรือละโดเมนย่อยโดยไม่จำเป็นและใช้โปรโตคอล HTTP ที่ไม่ถูกต้อง
{"origin": "http://www.web.dev"}
ต้นทางนี้รวมโปรโตคอล http://
และโดเมนย่อย www.
ไม่ถูกต้อง
{"origin": "https://web.dev"}
ต้นทางนี้นำทางแบบสาธารณะได้
หากต้นทางที่ขอเป็นเวอร์ชันการนำทาง ข้อผิดพลาดนี้อาจเกิดขึ้นด้วยหากต้นทางมีจำนวนตัวอย่างไม่เพียงพอ ต้นทางและ URL ทั้งหมดที่รวมอยู่ในชุดข้อมูลต้องมีตัวอย่างในจำนวนมากพอที่จะลบข้อมูลระบุตัวบุคคลของผู้ใช้แต่ละราย นอกจากนี้ ต้นทางและ URL ต้องจัดทำดัชนีได้แบบสาธารณะ โปรดดูระเบียบวิธี CrUX เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีรวมเว็บไซต์ในชุดข้อมูล
ข้อมูล URL ของการค้นหา
คุณได้ทราบวิธีค้นหา CrUX API สำหรับประสบการณ์ของผู้ใช้โดยรวมในต้นทางแล้ว หากต้องการจำกัดผลลัพธ์ไว้ที่หน้าเว็บใดหน้าเว็บหนึ่ง ให้ใช้พารามิเตอร์คำขอ 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/"}'
คำสั่ง cURL นี้คล้ายกับตัวอย่างต้นทาง เว้นแต่ว่าส่วนเนื้อหาของคำขอจะใช้พารามิเตอร์ url
เพื่อระบุหน้าเว็บที่จะค้นหา
หากต้องการค้นหาข้อมูล URL จาก CrUX API ใน JavaScript ให้เรียกฟังก์ชัน CrUXApiUtil.query
โดยใช้พารามิเตอร์ url
ในเนื้อหาคำขอ
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
หากมีข้อมูลสำหรับ URL นี้อยู่ในชุดข้อมูล CrUX API จะส่งกลับการตอบกลับที่เข้ารหัสด้วย JSON เช่น
{
"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
}
},
// ...
}
}
}
มีรูปแบบทุกประการ ผลลัพธ์แสดงว่า https://web.dev/fast/
มีคะแนน "ดี" 85% การใช้งาน LCP และเปอร์เซ็นไทล์ที่ 75 ที่ 1,947 มิลลิวินาที ซึ่งดีกว่าการกระจายทั่วทั้งต้นทางเล็กน้อย
การปรับ URL ให้เป็นมาตรฐาน
CrUX API อาจปรับ URL ที่ขอให้เป็นมาตรฐานเพื่อให้ตรงกับรายการ URL ที่รู้จักมากขึ้น เช่น การค้นหา URL https://web.dev/fast/#measure-performance-in-the-field
จะแสดงข้อมูลสำหรับ https://web.dev/fast/
เนื่องจากมีการทำให้เป็นมาตรฐาน ในกรณีนี้ ระบบจะรวมออบเจ็กต์ urlNormalizationDetails
ไว้ในคำตอบ
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": { ... }
},
"urlNormalizationDetails": {
"normalizedUrl": "https://web.dev/fast/",
"originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
}
}
ดูข้อมูลเพิ่มเติมเกี่ยวกับการปรับ URL ให้เป็นมาตรฐานในเอกสารประกอบของ CrUX
ค้นหาตามรูปแบบของอุปกรณ์
ประสบการณ์ของผู้ใช้อาจแตกต่างกันอย่างมากตามการเพิ่มประสิทธิภาพเว็บไซต์ เงื่อนไขเครือข่าย และผู้ใช้ อุปกรณ์ เจาะลึกเกี่ยวกับประสิทธิภาพของต้นทางและ URL โดยใช้มิติข้อมูล formFactor
ของ CrUX API เพื่อทำความเข้าใจความแตกต่างเหล่านี้ให้ดียิ่งขึ้น
API รองรับค่ารูปแบบของอุปกรณ์ที่ชัดเจน 3 ค่า ได้แก่ DESKTOP
, PHONE
และ TABLET
นอกเหนือจากต้นทางหรือ URL ให้ระบุค่าใดค่าหนึ่งต่อไปนี้ในเนื้อความของคำขอเพื่อจำกัดผลลัพธ์เฉพาะประสบการณ์ของผู้ใช้ดังกล่าวเท่านั้น ตัวอย่างนี้แสดงวิธีการค้นหา API ตามรูปแบบของอุปกรณ์โดยใช้ 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"}'
หากต้องการค้นหา CrUX API สำหรับข้อมูลเฉพาะรูปแบบของอุปกรณ์โดยใช้ JavaScript ให้เรียกใช้ฟังก์ชัน CrUXApiUtil.query
โดยใช้พารามิเตอร์ url
และ formFactor
ในเนื้อหาคำขอ
CrUXApiUtil.query({
url: 'https://web.dev/fast/',
formFactor: 'PHONE'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
การละเว้นพารามิเตอร์ formFactor
จะเทียบเท่ากับการขอข้อมูลสำหรับรูปแบบของอุปกรณ์ทั้งหมดรวมกัน
{
"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
}
},
// ...
}
}
}
ฟิลด์ key
ของคำตอบจะสะท้อนกลับการกำหนดค่าคำขอ formFactor
เพื่อยืนยันว่าจะรวมเฉพาะประสบการณ์การใช้งานโทรศัพท์เท่านั้น
จำจากส่วนก่อนหน้าได้ว่า 85% ของประสบการณ์ของผู้ใช้ในหน้านี้อยู่ในระดับ "ดี" LCP เปรียบเทียบกับประสบการณ์การใช้งานโทรศัพท์โดยเฉพาะ ซึ่งมีเพียง 78% ที่ถือว่า "ดี" นอกจากนี้เปอร์เซ็นไทล์ที่ 75 ยังช้ากว่าในบรรดาประสบการณ์การใช้งานโทรศัพท์อีกด้วย โดยเพิ่มขึ้นจาก 1,947 มิลลิวินาที เป็น 2,366 มิลลิวินาที การแบ่งกลุ่มตามรูปแบบของอุปกรณ์มีโอกาสเน้นความแตกต่างอย่างมากต่อประสบการณ์ของผู้ใช้
ประเมินประสิทธิภาพของ Core Web Vitals
โปรแกรม Core Web Vitals จะกำหนดเป้าหมายที่ช่วยตัดสินว่าประสบการณ์ของผู้ใช้หรือการเผยแพร่ประสบการณ์จะถือว่า "ดี" หรือไม่ ในตัวอย่างต่อไปนี้ เราใช้ CrUX API และฟังก์ชัน CrUXApiUtil.query
เพื่อประเมินว่าการกระจายเมตริก Core Web Vitals (LCP, FID, CLS) ของหน้าเว็บนั้น "ดี" หรือไม่
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}).`)
});
}
ผลลัพธ์แสดงให้เห็นว่าหน้านี้ผ่านการประเมิน Core Web Vitals สำหรับเมตริกทั้ง 3 รายการ
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).
เมื่อรวมกับวิธีการอัตโนมัติในการตรวจสอบผลลัพธ์ของ API คุณจะใช้ข้อมูลจาก CrUX เพื่อดูแลให้ประสบการณ์ของผู้ใช้จริงทำงานได้อย่างรวดเร็วและรวดเร็ว ดูข้อมูลเพิ่มเติมเกี่ยวกับ Core Web Vitals และวิธีวัดผลได้ที่ Web Vitals และเครื่องมือสำหรับวัด Core Web Vitals
ขั้นตอนถัดไปคือ
ฟีเจอร์ที่รวมอยู่ใน CrUX API เวอร์ชันแรกของ CrUX API เป็นเพียงจุดเริ่มต้นของข้อมูลเชิงลึกที่เป็นไปได้ใน CrUX ผู้ใช้ชุดข้อมูล CrUX ใน BigQuery อาจคุ้นเคยกับฟีเจอร์ขั้นสูงเพิ่มเติมบางอย่าง ได้แก่
- เมตริกเพิ่มเติม
first_paint
dom_content_loaded
onload
time_to_first_byte
notification_permissions
- มิติข้อมูลเพิ่มเติม
month
country
effective connection type
(ECT)
- รายละเอียดเพิ่มเติม
- ฮิสโตแกรมแบบละเอียด
- เปอร์เซ็นไทล์เพิ่มเติม
ดูเอกสาร CrUX API อย่างเป็นทางการเพื่อรับคีย์ API และสำรวจแอปพลิเคชันตัวอย่างเพิ่มเติม เราหวังว่าคุณจะลองใช้และอยากทราบคำถามหรือความคิดเห็นของคุณ ดังนั้นโปรดติดต่อเราในฟอรัมสนทนา CrUX และหากต้องการติดตามข้อมูลเกี่ยวกับทุกอย่างที่เราวางแผนไว้สำหรับ CrUX API โปรดสมัครรับฟอรัมประกาศของ CrUX หรือติดตามเราทาง Twitter ที่ @ChromeUXReport