วิธีใช้ CrUX API

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

Rick Viscomi
Rick Viscomi
Shane Exterkamp
Shane Exterkamp

ชุดข้อมูลรายงาน 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