วิธีใช้ CrUX API

ดูวิธีใช้ Chrome UX Report API เพื่อเข้าถึงข้อมูลประสบการณ์ของผู้ใช้จริงในเว็บไซต์หลายล้านเว็บไซต์

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

ชุดข้อมูลรายงาน UX ของ Chrome (CrUX) แสดงให้เห็นว่าผู้ใช้ Chrome ในชีวิตจริงมีการใช้งานเว็บไซต์ที่ได้รับความนิยมในเว็บอย่างไร ตั้งแต่ปี 2017 ซึ่งเป็นปีที่เปิดตัวชุดข้อมูลที่ค้นหาได้เป็นครั้งแรกใน BigQuery เราได้ผสานรวมข้อมูลภาคสนามจาก CrUX เข้ากับเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ เช่น PageSpeed Insights และรายงาน Core Web Vitals ของ Search Console เพื่อช่วยให้นักพัฒนาซอฟต์แวร์วัดและตรวจสอบประสบการณ์ของผู้ใช้จริงได้ สิ่งที่ขาดหายไปตลอดมาคือเครื่องมือที่ให้สิทธิ์เข้าถึงข้อมูล CrUX แบบ RESTful โดยไม่มีค่าใช้จ่ายผ่านโปรแกรม เราจึงยินดีที่จะประกาศเปิดตัว Chrome UX Report API เวอร์ชันใหม่ล่าสุดเพื่อช่วยลดช่องว่างดังกล่าว

API นี้สร้างขึ้นโดยมีเป้าหมายเพื่อให้นักพัฒนาแอปเข้าถึงข้อมูล CrUX ได้อย่างรวดเร็วและครอบคลุม CrUX API จะรายงานเฉพาะข้อมูลประสบการณ์ของผู้ใช้ภาคสนาม ซึ่งแตกต่างจาก PageSpeed Insights API ที่มีอยู่ ซึ่งจะรายงานข้อมูลห้องทดลองจากการตรวจสอบประสิทธิภาพของ Lighthouse ด้วย CrUX API ได้รับการเพิ่มประสิทธิภาพและสามารถแสดงข้อมูลประสบการณ์ของผู้ใช้ได้อย่างรวดเร็ว จึงเหมาะอย่างยิ่งสำหรับแอปพลิเคชันการตรวจสอบแบบเรียลไทม์

CrUX API จะตรวจสอบและติดตาม Largest Contentful Paint (LCP), Interaction to Next Paint (INP) และ Cumulative Layout Shift (CLS) ทั้งในระดับต้นทางและ URL เพื่อให้มั่นใจว่านักพัฒนาซอฟต์แวร์จะเข้าถึงเมตริกทั้งหมดที่สำคัญที่สุดได้ ซึ่งก็คือ Core Web Vitals

มาดูวิธีใช้กันเลย

ลองใช้ API ในหน้านี้

ลองใช้งาน

ข้อมูลต้นทางของการค้นหา

ต้นทางในชุดข้อมูล 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 ส่วนดังนี้

  1. ปลายทาง URL ของ API รวมถึงคีย์ API ส่วนตัวของผู้เรียก
  2. ส่วนหัว Content-Type: application/json ซึ่งบ่งบอกว่าเนื้อความของคำขอมี JSON
  3. เนื้อหาคำขอที่เข้ารหัส 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 พร็อพเพอร์ตี้แสดงสัดส่วนของประสบการณ์ของผู้ใช้ภายในช่วงนั้น ในตัวอย่างนี้ ประสบการณ์ของผู้ใช้ LCP 79% ในหน้าเว็บทั้งหมดของ web.dev อยู่ต่ำกว่า 2,500 มิลลิวินาที ซึ่งเป็นเกณฑ์ LCP ที่ "ดี" percentiles.p75 ค่านี้หมายความว่าประสบการณ์ของผู้ใช้ 75% ในการกระจายนี้มีค่าน้อยกว่า 2,216 มิลลิวินาที ดูข้อมูลเพิ่มเติมเกี่ยวกับโครงสร้างการตอบกลับได้ในเอกสารประกอบเนื้อหาการตอบกลับ

ข้อผิดพลาด

เมื่อ CrUX API ไม่มีข้อมูลสำหรับต้นทางที่ระบุ 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

คุณได้เห็นวิธีค้นหา API ของ CrUX เพื่อดูประสบการณ์ของผู้ใช้โดยรวมในต้นทางแล้ว หากต้องการจำกัดผลลัพธ์ให้แสดงเฉพาะหน้าเว็บใดหน้าเว็บหนึ่ง ให้ใช้พารามิเตอร์คำขอ 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/ มีประสบการณ์ LCP ที่ "ดี" 85% และเปอร์เซ็นไทล์ที่ 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, INP, CLS) ของหน้าเว็บนั้น "ดี" หรือไม่

CrUXApiUtil.query({   url: 'https://web.dev/fast/' }).then(response => {   assessCoreWebVitals(response); }).catch(response => {   console.error(response); });  function assessCoreWebVitals(response) {   // See https://web.dev/articles/vitals/#core-web-vitals.   const CORE_WEB_VITALS = [     'largest_contentful_paint',     'interaction_to_next_paint',     '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 interaction_to_next_paint passes the Core Web Vitals "good" threshold (200). 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 สามารถให้ได้ ผู้ใช้ชุดข้อมูล CrUX ใน BigQuery อาจคุ้นเคยกับฟีเจอร์ขั้นสูงบางอย่าง เช่น

  • เมตริกเพิ่มเติม
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • มิติข้อมูลเพิ่มเติม
    • month
    • country
  • รายละเอียดเพิ่มเติม
    • ฮิสโตแกรมแบบละเอียด
    • เปอร์เซ็นไทล์เพิ่มเติม

ดูเอกสารประกอบเกี่ยวกับ CrUX API อย่างเป็นทางการเพื่อรับคีย์ API และดูตัวอย่างแอปพลิเคชันเพิ่มเติม เราหวังว่าคุณจะลองใช้ฟีเจอร์นี้ และยินดีรับฟังคำถามหรือความคิดเห็นจากคุณ โปรดติดต่อเราในฟอรัมสนทนาของ CrUX และหากต้องการติดตามข่าวสารล่าสุดเกี่ยวกับทุกสิ่งที่เราวางแผนไว้สำหรับ CrUX API โปรดติดตามฟอรัมประกาศของ CrUX หรือติดตามเราบน Twitter ที่ @ChromeUXReport