วิธีใช้ CrUX History API

Johannes Henkel
Jasmine Yan
Jasmine Yan
GitHub
Barry Pollard

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

เมื่อใช้ร่วมกับการอัปเดตรายวันจากปลายทาง CrUX 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 การใช้คีย์ CrUX API เดียวกันกับการเรียกก่อนหน้านี้จะมีผล

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 ถึง 2, 500 มิลลิวินาทีของเมตริก 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% มีค่าระหว่าง 2,500 มิลลิวินาทีถึง 4,2000 มิลลิวินาที และ 5.27% มีค่าระหว่าง 2,500 มิลลิวินาทีถึง 4,2000 มิลลิวินาที

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

แม้ว่าตัวอย่างจะแสดงรายการอนุกรมเวลาและระยะเวลาเก็บข้อมูลเพียง 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 สําหรับระยะเวลาการรวบรวมข้อมูลแต่ละช่วง

ต่อไปนี้เป็นกราฟสำหรับอนุกรมเวลาของฮิสโตแกรมหรือแผนภูมิ Tri-bin เนื่องจากฮิสโตแกรมเหล่านี้มี Bin 3 ช่อง

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

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

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

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

Colab นี้ช่วยให้คุณสร้างแผนภูมิ p75, แผนภูมิ Tri-bin, รับข้อมูลในรูปแบบตาราง รวมถึงดูคู่คำขอและคำตอบสำหรับ 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