วิธีใช้ CrUX API

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

Rick Viscomi

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), Interaction to Next Paint (INP) และ Cumulative Layout Shift (CLS) ทั้งในระดับต้นทางและระดับ URL

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

ลองใช้ 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"}'

หมายเหตุ: คำขอ API ทั้งหมดต้องระบุค่าสำหรับพารามิเตอร์ key โดย [YOUR_API_KEY] ในตัวอย่างก่อนหน้านี้จะเป็นตัวยึดตำแหน่ง รับคีย์ CrUX API ส่วนตัวของคุณเองตามที่อธิบายไว้ในเอกสารประกอบของ CrUX API

คำสั่ง 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 แสดงสัดส่วนประสบการณ์ของผู้ใช้ภายในช่วงนั้น ในตัวอย่างนี้ 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/ มี 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 เพื่อยืนยันว่ามีเฉพาะประสบการณ์การใช้งานบนโทรศัพท์เท่านั้น

ข้อควรระวัง: ยิ่งคำขอมีความละเอียดมากเท่าใด เช่น การรวม URL กับรูปแบบที่เฉพาะเจาะจง ก็ยิ่งจะมีประสบการณ์ของผู้ใช้น้อยลงเท่านั้น ซึ่งอาจทําให้ข้อผิดพลาด "ไม่พบ" เกิดขึ้นบ่อยขึ้น โดยเฉพาะเมื่อค้นหา URL ที่ไม่ได้รับความนิยมมากนักหรืออุปกรณ์แท็บเล็ตประเภทที่ไม่ได้รับความนิยมมากนัก

โปรดจำไว้ว่าจากส่วนก่อนหน้านี้ 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}).`)
  });
}

ประเด็นสำคัญ: คุณเรียกใช้ API ได้ครั้งละ 1 ต้นทางหรือ URL เท่านั้น หากต้องการประเมินเว็บไซต์หรือหน้าเว็บหลายรายการ ให้เรียกใช้ API แยกกัน

ผลลัพธ์แสดงให้เห็นว่าหน้านี้ผ่านการประเมิน 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
  • effective connection type (ECT)
• รายละเอียดเพิ่มเติม
  • ฮิสโตแกรมแบบละเอียด
  • เปอร์เซ็นต์ไทล์เพิ่มเติม

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