วิธีใช้ CrUX History API

Johannes Henkel

Jasmine Yan

Barry Pollard

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

เมื่อใช้ร่วมกับการอัปเดตรายวันจากอุปกรณ์ปลายทาง 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 ถึง 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 น้อยกว่า 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 ดังต่อไปนี้

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

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

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

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

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