วิธีใช้ CrUX API

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

ชุดข้อมูลรายงาน 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 ที่มีอยู่ ซึ่งจะรายงานข้อมูลในห้องทดลองจากการตรวจสอบประสิทธิภาพ Lighthouse ด้วย CrUX API ได้รับการปรับปรุงให้มีประสิทธิภาพและแสดงข้อมูลประสบการณ์ของผู้ใช้ได้อย่างรวดเร็ว จึงเหมาะสำหรับแอปพลิเคชันการตรวจสอบแบบเรียลไทม์

เพื่อให้มั่นใจว่านักพัฒนาแอปมีสิทธิ์เข้าถึงเมตริกทั้งหมดที่สำคัญที่สุด ซึ่งได้แก่ Core Web Vitals 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 ส่วนดังนี้

  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 และส่งในออบเจ็กต์ requestbody

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

หากมีข้อมูลสำหรับต้นทางนี้ การตอบกลับของ API จะเป็นออบเจ็กต์ที่เข้ารหัสด้วย JSON ซึ่งมีmetricsที่แสดงถึงการกระจายประสบการณ์ของผู้ใช้ เมตริกการแจกแจงคือถังฮิสโตแกรมและเปอร์เซ็นไทล์

{
  "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. อย่างไม่ถูกต้อง

Success
{"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/ มีประสบการณ์ 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, 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 ผู้ใช้ชุดข้อมูล 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