วิธีใช้ CrUX History API

Johannes Henkel
Johannes Henkel
X GitHub Mastodon
Jasmine Yan
Jasmine Yan
GitHub
Barry Pollard

คู่มือนี้จะแนะนำปลายทาง Chrome UX Report (CrUX) History API ซึ่งให้ข้อมูลอนุกรมเวลาของประสิทธิภาพเว็บ ข้อมูลนี้จะอัปเดตทุกสัปดาห์และช่วยให้คุณเห็นประวัติข้อมูลได้ประมาณ 6 เดือน โดยจะเว้นระยะข้อมูล 25 จุดในแต่ละสัปดาห์

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

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

ลองใช้งาน

ค้นหา CrUX API รายวัน

สรุปจากบทความก่อนหน้าเกี่ยวกับ CrUX API คุณสามารถดูภาพรวมของข้อมูลภาคสนามสําหรับต้นทางหนึ่งๆ ได้ด้วยวิธีนี้

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"}'

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [{
          "start": 0, "end": 2500, "density": 0.9192
        }, {
          "start": 2500, "end": 4000, "density": 0.0513
        }, {
          "start": 4000, "density": 0.0294
        }],
        "percentiles": {
          "p75": 1303
        }
      }
      // ...
    },
    "collectionPeriod": {
      "firstDate": { "year": 2022, "month": 12, "day": 27 },
      "lastDate": { "year": 2023, "month": 1, "day": 23 }
    }
  }
}

ภาพรวมนี้ประกอบด้วยค่าความหนาแน่นของฮิสโตแกรมและค่าเปอร์เซ็นไทล์สำหรับระยะเวลาการเก็บรวบรวม 28 วันหนึ่งๆ ซึ่งในกรณีนี้ก็คือตั้งแต่วันที่ 27 ธันวาคม 2022 ถึง 23 มกราคม 2023

ค้นหา CrUX History API

หากต้องการเรียกใช้ปลายทางประวัติ ให้เปลี่ยน queryRecord ใน URL เป็น queryHistoryRecord ในคําสั่ง curl คุณใช้คีย์ API ของ CruX เดียวกันกับการเรียกก่อนหน้านี้ได้

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"origin": "https://web.dev"}'

รูปร่างโดยรวมของคำตอบจะคล้ายกัน แต่จะมีข้อมูลมากกว่ามาก ตอนนี้อนุกรมเวลาของฟิลด์ที่มีค่าเปอร์เซ็นไทล์ที่ 75 (p75) และค่าความหนาแน่นของฮิสโตแกรมจะแสดงแทนจุดข้อมูลเดียว

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogramTimeseries": [{
            "start": 0, "end": 2500, "densities": [
              0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
            ]
          }, {
            "start": 2500, "end": 4000, "densities": [
              0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
            ]
          },  {
            "start": 4000, "densities": [
              0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
            ]
          }
        ],
        "percentilesTimeseries": {
          "p75s": [
            1362, 1352, 1344, 1356, 1366, 1377
          ]
        }
      }
      // ...
    },
    "collectionPeriods": [{
        "firstDate": { "year": 2022, "month": 7, "day": 10 },
        "lastDate": { "year": 2022, "month": 8, "day": 6 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 17 },
        "lastDate": { "year": 2022, "month": 8, "day": 13 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 24 },
        "lastDate": { "year": 2022, "month": 8, "day": 20 }
      }, {
        "firstDate": { "year": 2022, "month": 7, "day": 31 },
        "lastDate": { "year": 2022, "month": 8, "day": 27 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 7 },
        "lastDate": { "year": 2022, "month": 9, "day": 3 }
      }, {
        "firstDate": { "year": 2022, "month": 8, "day": 14 },
        "lastDate": { "year": 2022, "month": 9, "day": 10 }
      }
    ]
  }
}

ในตัวอย่างนี้ อนุกรมเวลา densities สำหรับกลุ่ม 0-2500 มิลลิวินาทีของเมตริก Largest Contentful Paint (LCP) คือ [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187]. ความหนาแน่นแต่ละรายการเหล่านี้สังเกตได้ในระหว่างรายการ collectionPeriods ที่เกี่ยวข้อง เช่น ความหนาแน่นที่ 5 ซึ่งเท่ากับ 0.9183 คือความหนาแน่นของระยะเวลาการเก็บรวบรวมที่ 5 ซึ่งสิ้นสุดในวันที่ 3 กันยายน 2022 และ 0.9187 คือความหนาแน่นของระยะเวลาที่สิ้นสุดในสัปดาห์หลังจากนั้น

กล่าวคือ การตีความรายการอนุกรมเวลาล่าสุดในตัวอย่างสำหรับ https://web.dev พบว่าตั้งแต่วันที่ 14 สิงหาคม 2022 ถึงวันที่ 10 กันยายน 2022 การโหลดหน้าเว็บ 91.87% มีค่า LCP น้อยกว่า 2,500 มิลลิวินาที, 5.27% มีค่าระหว่าง 2500 มิลลิวินาที ถึง 40.84 มิลลิวินาที และ 0.27% มีค่ามากกว่า 2,500 มิลลิวินาที และ 40.84 มิลลิวินาที

ในทํานองเดียวกัน ก็มีอนุกรมเวลาสําหรับค่า p75: LCP p75 สําหรับวันที่ 14 สิงหาคม 2022 ถึง 10 กันยายน 2022 คือ 1377 ซึ่งหมายความว่าในระยะเวลาการเก็บรวบรวมนี้ ประสบการณ์ของผู้ใช้ 75% มี LCP น้อยกว่า 1377 มิลลิวินาที และประสบการณ์ของผู้ใช้ 25% มี LCP มากกว่า 1377 มิลลิวินาที

แม้ว่าตัวอย่างจะแสดงรายการอนุกรมเวลาและระยะเวลาการเก็บรวบรวมเพียง 6 รายการ แต่การตอบกลับจาก API จะให้รายการอนุกรมเวลา 25 รายการ เนื่องจากวันที่สิ้นสุดของระยะเวลาการเก็บรวบรวมแต่ละรายการคือวันเสาร์ที่ห่างกัน 7 วัน จึงครอบคลุมระยะเวลา 6 เดือน

ในการตอบกลับหนึ่งๆ ความยาวของอนุกรมเวลาสำหรับความหนาแน่นของถังฮิสโตแกรมและค่า p75 จะตรงกับความยาวของอาร์เรย์ในฟิลด์ collectionPeriods ทุกประการ กล่าวคือ มีการติดต่อแบบหนึ่งต่อหนึ่งตามดัชนีในอาร์เรย์เหล่านี้

ค้นหาข้อมูลระดับหน้าเว็บ

นอกจากข้อมูลระดับต้นทางแล้ว CrUX History API ยังช่วยให้เข้าถึงข้อมูลย้อนหลังระดับหน้าเว็บได้ด้วย แม้ว่าก่อนหน้านี้ข้อมูลระดับต้นทางจะพร้อมให้ใช้งานผ่านชุดข้อมูล CrUX ใน BigQuery (หรือใช้แดชบอร์ด CrUX) แต่ข้อมูลย้อนหลังระดับหน้าเว็บจะใช้ได้เฉพาะเมื่อเว็บไซต์รวบรวมและจัดเก็บข้อมูลเองเท่านั้น ตอนนี้ API ใหม่นี้ปลดล็อกข้อมูลระดับหน้าเว็บที่ผ่านมาแล้ว

คุณสามารถค้นหาข้อมูลระดับหน้าเว็บในลักษณะเดียวกันได้ โดยใช้ url แทน origin ในเพย์โหลด

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{"url": "https://web.dev/blog/"}'

ข้อมูลย้อนหลังระดับหน้า (และระดับต้นทาง) อยู่ภายใต้ข้อกําหนดของการได้รับสิทธิ์เดียวกันกับ CrUX ที่เหลือ ดังนั้นหน้าเว็บบางหน้าจึงอาจมีบันทึกย้อนหลังที่ไม่สมบูรณ์ ในกรณีเหล่านี้ ข้อมูลที่ "ขาดหายไป" จะแสดงด้วย "NaN" สำหรับความหนาแน่น histogramTimeseries และ null สำหรับ percentilesTimeseries สาเหตุของความแตกต่างคือความหนาแน่นของฮิสโตแกรมเป็นตัวเลขเสมอ ในขณะที่เปอร์เซ็นไทล์อาจเป็นตัวเลขหรือสตริง (CLS ใช้สตริง แม้ว่าจะดูเป็นตัวเลขก็ตาม)

แสดงข้อมูลเป็นภาพ

คุณอาจสงสัยว่าเหตุใดข้อมูลจึงมีรูปแบบนี้ เราพบว่าวิธีนี้ช่วยให้สร้างกราฟได้ง่ายขึ้น ตัวอย่างเช่น กราฟนี้แสดงค่า p75 สำหรับ Interaction To Next Paint (INP) ของ https://web.dev

กราฟอนุกรมเวลาของค่า p75 ที่แสดงการถดถอยในช่วงเดือนพฤศจิกายน 2022

ในแผนภูมิเส้นนี้ แต่ละค่าบนแกน y คือค่า p75 จากอนุกรมเวลา p75s และแกน x คือเวลา ซึ่งตั้งค่าเป็น lastDate สำหรับแต่ละระยะเวลาการรวบรวมข้อมูล

กราฟนี้เป็นอนุกรมเวลาของกลุ่มข้อมูลฮิสโตแกรม ซึ่งเรียกว่าแผนภูมิกลุ่มข้อมูล 3 กลุ่ม เนื่องจากฮิสโตแกรมเหล่านี้มีกลุ่มข้อมูล 3 กลุ่ม

แผนภูมิแท่งซ้อนแสดงการเปลี่ยนแปลงของอัตราส่วนสัมพัทธ์ของ "ดี" "ต้องปรับปรุง" และ "แย่" เมื่อเวลาผ่านไป

แกน x จะตั้งค่าเป็น lastDate สําหรับระยะเวลาการเก็บรวบรวมแต่ละครั้ง แต่ครั้งนี้แกน Y คือเปอร์เซ็นต์ของการโหลดหน้าเว็บที่อยู่ในช่วงที่เจาะจงสําหรับเมตริก INP ซึ่งแสดงผ่านแผนภูมิแท่งซ้อน แผนภูมิ p75 ให้ภาพรวมคร่าวๆ และภายในแผนภูมิเดียว คุณเพิ่มเมตริกหลายรายการหรือแสดงเส้นทั้ง PHONE และ DESKTOP ได้ค่อนข้างง่าย แผนภูมิ 3 กล่องแสดงการแจกแจงค่าเมตริกที่วัดได้ในช่วงการเก็บรวบรวมแต่ละครั้ง

ตัวอย่างเช่น แม้ว่าแผนภูมิ p75 จะระบุว่า https://web.dev มีค่า INP ที่ยอมรับได้เกือบทั้งหมดในช่วงสังเกตการณ์ แต่แผนภูมิ 3 กล่องแสดงว่า INP นั้นแย่มากสำหรับการโหลดหน้าเว็บเพียงส่วนน้อย ในทั้ง 2 แผนภูมิ เราอนุมานได้ง่ายๆ ว่าประสิทธิภาพลดลงซึ่งเริ่มตั้งแต่ช่วงสิ้นเดือนตุลาคม และได้รับการแก้ไขภายในกลางเดือนพฤศจิกายน

หากต้องการสร้างแผนภูมิดังกล่าวด้วยตนเอง เราได้สร้าง Colab ตัวอย่างไว้ให้ Colab หรือ "Colaboratory" ช่วยให้คุณเขียนและเรียกใช้ Python จากในเบราว์เซอร์ได้ CrUX History API Colab (แหล่งที่มา) ใช้ Python เพื่อเรียก API และสร้างแผนภูมิข้อมูล

Colab นี้ช่วยให้คุณสร้างแผนภูมิ p75, แผนภูมิ 3 กล่องรับข้อมูล, รับข้อมูลในรูปแบบตาราง และดูคู่คําขอและการตอบกลับสําหรับ CrUX API ได้โดยกรอกแบบฟอร์มสั้นๆ คุณไม่ต้องเป็นโปรแกรมเมอร์ก็ใช้โค้ดนี้ได้ แต่คุณต้องดูโค้ด Python แล้วแก้ไขโค้ดให้เจ๋งขึ้นได้! โปรดเพลิดเพลินและแสดงความคิดเห็นเกี่ยวกับสิ่งที่พบ

แน่นอนว่าคุณใช้ Colab หรือ Python ไม่ได้เพียงอย่างเดียว และนี่เป็นเพียงตัวอย่างวิธีใช้ API ใหม่นี้ เนื่องจากเป็นปลายทาง HTTP ที่อิงตาม JSON คุณจึงค้นหา API ได้จากเทคโนโลยีใดก็ได้

บทสรุป

ก่อนการเปิดตัวปลายทาง CrUX History API เจ้าของเว็บไซต์มีข้อจำกัดในข้อมูลประวัติที่หาได้จาก CrUX ข้อมูลระดับต้นทางรายเดือนมีให้ใช้งานโดยใช้ BigQuery และหน้าแดชบอร์ด CrUX แต่ไม่มีข้อมูลรายสัปดาห์หรือข้อมูลย้อนหลังระดับหน้าเว็บ เจ้าของเว็บไซต์สามารถบันทึกข้อมูลนี้ด้วยตนเองได้โดยใช้ API รายวัน แต่มักพบว่าจําเป็นต้องใช้หลังจากเมตริกถดถอย

เราหวังว่าการเปิดตัว CrUX History API นี้จะช่วยให้เจ้าของเว็บไซต์เข้าใจเมตริกของเว็บไซต์ที่เปลี่ยนแปลงไปได้ดียิ่งขึ้น รวมถึงใช้เป็นเครื่องมือในการวินิจฉัยเมื่อเกิดปัญหา หากคุณใช้ API ใหม่ เรายินดีรับฟังความคิดเห็นของคุณที่ กลุ่ม Google สำหรับรายงาน UX ของ Chrome (การสนทนา)

กิตติกรรมประกาศ

รูปภาพหลักโดย Dave Herring ใน Unsplash