API ของ CrUX

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

ลองใช้งาน

กรณีการใช้งานทั่วไป

CrUX API ช่วยให้สามารถค้นหาเมตริกประสบการณ์ของผู้ใช้สำหรับ URI ที่เฉพาะเจาะจง เช่น "รับเมตริกสำหรับต้นทาง https://example.com"

คีย์ API ของ CrUX

การใช้ CrUX API ต้องใช้คีย์ Google Cloud API ที่จัดสรรไว้สำหรับการใช้งาน Chrome UX Report API

การรับและการใช้คีย์ API

หรือสร้างคีย์ในหน้าข้อมูลเข้าสู่ระบบ

หลังจากมีคีย์ API แล้ว แอปพลิเคชันของคุณจะเพิ่มพารามิเตอร์การค้นหา key=yourAPIKey ต่อท้าย URL คำขอทั้งหมดได้

คีย์ API ปลอดภัยสำหรับการฝังใน URL โดยไม่จำเป็นต้องเข้ารหัสใดๆ

ดูตัวอย่างการค้นหา

โมเดลข้อมูล

ส่วนนี้จะอธิบายโครงสร้างของข้อมูลในคำขอและการตอบกลับ

บันทึก

ข้อมูลที่แยกกันเกี่ยวกับหน้าเว็บหรือเว็บไซต์ ระเบียนอาจมีข้อมูลที่เจาะจงสำหรับตัวระบุและชุดค่าผสมของมิติข้อมูลที่เฉพาะเจาะจง ระเบียนหนึ่งๆ อาจมีข้อมูลสำหรับเมตริกอย่างน้อย 1 รายการ

รหัสระบุ

ตัวระบุจะระบุระเบียนที่ควรค้นหา ใน CrUX ตัวระบุเหล่านี้คือหน้าเว็บและเว็บไซต์

Origin

เมื่อตัวระบุเป็นต้นทาง ระบบจะรวบรวมข้อมูลทั้งหมดที่มีอยู่สำหรับทุกหน้าในต้นทางนั้นเข้าด้วยกัน ตัวอย่างเช่น สมมติว่าต้นทาง http://www.example.com มีหน้าเว็บที่จัดวางตาม Sitemap นี้

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

ซึ่งหมายความว่าเมื่อค้นหารายงาน Chrome UX โดยตั้งค่าต้นทางเป็น http://www.example.com ระบบจะแสดงข้อมูลสำหรับ http://www.example.com/, http://www.example.com/foo.html และ http://www.example.com/bar.html โดยรวมเข้าด้วยกัน เนื่องจากหน้าเว็บทั้งหมดอยู่ภายใต้ต้นทางนั้น

URL

เมื่อตัวระบุเป็น URL ระบบจะแสดงเฉพาะข้อมูลของ URL นั้นๆ เมื่อดู Sitemap ต้นทางของ http://www.example.com อีกครั้ง

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

หากตั้งค่าตัวระบุเป็น URL ที่มีค่าเป็น http://www.example.com/foo.html ระบบจะแสดงเฉพาะข้อมูลของหน้าเว็บนั้น

ขนาด

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

รูปแบบ

คลาสอุปกรณ์ที่ผู้ใช้ปลายทางใช้เพื่อไปยังหน้าเว็บ นี่คือคลาสทั่วไปของอุปกรณ์ที่แบ่งออกเป็น PHONE, TABLET และ DESKTOP

เมตริก

เรารายงานเมตริกเป็นการรวมทางสถิติในฮิสโตแกรม เปอร์เซ็นไทล์ และเศษส่วน

ค่าจุดลอยตัวจะปัดเศษเป็นทศนิยม 4 ตำแหน่ง (โปรดทราบว่าเมตริก cumulative_layout_shift เป็นค่า Double ที่เข้ารหัสเป็นสตริง จึงไม่ถือว่าเป็นค่าจุดลอยตัวและจะรายงานเป็นทศนิยม 2 ตำแหน่งภายในสตริง)

ฮิสโตแกรม

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

ฮิสโตแกรม 3 กลุ่มสำหรับเมตริกตัวอย่างจะมีลักษณะดังนี้

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

ข้อมูลนี้บ่งชี้ว่า 38.18% ของการโหลดหน้าเว็บมีการวัดเมตริกตัวอย่างระหว่าง 0 มิลลิวินาทีถึง 1,000 มิลลิวินาที หน่วยของเมตริกไม่ได้อยู่ในฮิสโตแกรมนี้ ในกรณีนี้ เราจะถือว่าเป็นมิลลิวินาที

นอกจากนี้ การโหลดหน้าเว็บ 49.91% มีค่าเมตริกระหว่าง 1,000 มิลลิวินาทีถึง 3,000 มิลลิวินาที และ 11.92% มีค่ามากกว่า 3,000 มิลลิวินาที

เปอร์เซ็นไทล์

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

{
  "percentiles": {
    "p75": 2063
  }
}

ในตัวอย่างนี้ การโหลดหน้าเว็บอย่างน้อย 75% ได้รับการวัดด้วยค่าเมตริก <= 2063

เศษส่วน

เศษส่วนจะระบุเปอร์เซ็นต์ของการโหลดหน้าเว็บที่ติดป้ายกำกับได้ในลักษณะเฉพาะ ในกรณีนี้ ค่าเมตริกคือป้ายกำกับเหล่านี้

ตัวอย่างเช่น เมตริก form_factors ประกอบด้วยออบเจ็กต์ fractions ที่แสดงรายละเอียดของรูปแบบของอุปกรณ์ (หรืออุปกรณ์) ที่การค้นหาหนึ่งๆ ครอบคลุม

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

ในกรณีนี้ ระบบวัดการโหลดหน้าเว็บ 3.77% บนเดสก์ท็อป 2.88% บนแท็บเล็ต และ 93.35% บนโทรศัพท์ ซึ่งรวมเป็น 100%

ประเภทค่าเมตริก

การแมปชื่อเมตริก BigQuery

ระยะเวลาการเก็บรวบรวม

ตั้งแต่เดือนตุลาคม 2022 เป็นต้นมา CrUX API มีออบเจ็กต์ collectionPeriod ที่มีฟิลด์ firstDate และ endDate ซึ่งแสดงวันที่เริ่มต้นและวันที่สิ้นสุดของกรอบเวลาการรวมข้อมูล เช่น

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

ซึ่งจะช่วยให้เข้าใจข้อมูลได้ดีขึ้น และทราบว่าข้อมูลได้รับการอัปเดตสำหรับวันนั้นแล้วหรือยัง หรือยังคงแสดงข้อมูลเดียวกับเมื่อวาน

ระยะเวลาการรวบรวมยังมีอยู่ใน PageSpeed Insights ด้วย ดังนี้

นอกจากนี้ collectionPeriod จะแสดงข้อมูล 28 วันเสมอ แม้ว่าข้อมูลจะไม่ใช่ข้อมูล 28 วันเต็มก็ตาม (เช่น หากหน้าเว็บเปิดตัวมาไม่ถึง 28 วัน) collectionPeriod คือระยะเวลาที่มีการรวบรวมข้อมูล CrUX ซึ่งไม่จำเป็นต้องเป็นระยะเวลาที่ข้อมูลแสดงถึง

ตัวอย่างการค้นหา

ระบบจะส่งคำค้นหาเป็นออบเจ็กต์ JSON โดยใช้คำขอ POST ไปยัง https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" พร้อมข้อมูลคำค้นหาเป็นออบเจ็กต์ JSON ในเนื้อหา POST ดังนี้

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

เช่น คุณเรียกใช้จาก curl ได้ด้วยบรรทัดคำสั่งต่อไปนี้ (แทนที่ API_KEY ด้วยคีย์ของคุณ)

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

ข้อมูลระดับหน้าเว็บจะพร้อมใช้งานผ่าน API โดยการส่งพร็อพเพอร์ตี้ url ในการค้นหาแทน origin ดังนี้

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

หากไม่ได้ตั้งค่าพร็อพเพอร์ตี้ metrics ระบบจะแสดงเมตริกที่ใช้ได้ทั้งหมด ดังนี้

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (รายงานเฉพาะในกรณีที่ไม่ได้ระบุ formFactor ในคำขอ)
• experimental_ad_count (รายงานเฉพาะหน้าเว็บที่รวมอยู่ในเมตริกโฆษณา)
• experimental_ad_density (รายงานเฉพาะหน้าเว็บที่รวมอยู่ในเมตริกโฆษณา)
• experimental_ad_cpu (รายงานเฉพาะหน้าเว็บที่รวมอยู่ในเมตริกโฆษณา)
• experimental_ad_kilobytes (รายงานเฉพาะหน้าเว็บที่รวมอยู่ในเมตริกโฆษณา)

หากไม่ได้ระบุค่า formFactor ระบบจะรวมค่าจากอุปกรณ์รูปแบบต่างๆ ทั้งหมด

ดูตัวอย่างการค้นหาเพิ่มเติมได้ที่การใช้รายงาน Chrome UX API

Data Pipeline

ชุดข้อมูล CrUX จะได้รับการประมวลผลผ่านไปป์ไลน์เพื่อรวม รวบรวม และกรองข้อมูลก่อนที่จะพร้อมใช้งานโดยใช้ API

รายได้เฉลี่ยต่อเนื่อง

ข้อมูลในรายงาน Chrome UX เป็นค่าเฉลี่ยต่อเนื่อง 28 วันของเมตริกที่รวบรวมไว้ ซึ่งหมายความว่าข้อมูลที่แสดงในรายงาน Chrome UX ณ เวลาใดก็ตามเป็นข้อมูลในช่วง 28 วันที่ผ่านมารวมกัน

ซึ่งคล้ายกับวิธีที่ชุดข้อมูล CrUX ใน BigQuery รวมรายงานรายเดือน

อัปเดตรายวัน

ข้อมูลจะอัปเดตทุกวันประมาณ 04:00 น. UTC ไม่มีข้อตกลงระดับการให้บริการสำหรับเวลาอัปเดต โดยจะดำเนินการตามความสามารถสูงสุดในทุกวัน

สคีมา

มีปลายทางเดียวสำหรับ CrUX API ซึ่งยอมรับคำขอ HTTP POST รายการ API จะแสดงผล record ซึ่งมี metrics อย่างน้อย 1 รายการที่สอดคล้องกับข้อมูลประสิทธิภาพเกี่ยวกับต้นทางหรือหน้าที่ขอ

คำขอ HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

URL ใช้ไวยากรณ์การแปลงรหัส gRPC

เนื้อความของคำขอ

เนื้อหาของคำขอควรมีข้อมูลซึ่งมีโครงสร้างดังต่อไปนี้

{
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

ตัวอย่างเช่น หากต้องการขอค่า Largest Contentful Paint บนเดสก์ท็อปสำหรับหน้าแรกของเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ Chrome ให้ทำดังนี้

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

เนื้อหาการตอบกลับ

คำขอที่สำเร็จจะแสดงผลการตอบกลับพร้อมออบเจ็กต์ record และ urlNormalizationDetails ในโครงสร้างต่อไปนี้

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

ตัวอย่างเช่น การตอบกลับเนื้อหาคำขอในคำขอก่อนหน้าอาจเป็นดังนี้

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

คีย์

Key กำหนดมิติข้อมูลทั้งหมดที่ระบุว่าระเบียนนี้ไม่ซ้ำกัน

{
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}

เมตริก

metric คือชุดข้อมูลประสบการณ์ของผู้ใช้ที่รวบรวมไว้สำหรับเมตริกประสิทธิภาพเว็บรายการเดียว เช่น First Contentful Paint ซึ่งอาจมีฮิสโตแกรมสรุปการใช้งาน Chrome ในชีวิตจริงเป็นชุด bins, ข้อมูลเปอร์เซ็นไทล์ที่เฉพาะเจาะจง (เช่น p75) หรืออาจมีเศษส่วนที่มีป้ายกำกับ

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

หรือ

{
  "fractions": {
    object (Fractions)
  }
}

ถัง

bin คือส่วนของข้อมูลที่ไม่ต่อเนื่องซึ่งครอบคลุมตั้งแต่ต้นจนจบ หรือหากไม่มีการระบุจุดสิ้นสุด ก็จะครอบคลุมตั้งแต่ต้นจนถึงค่าบวกอนันต์

ค่าเริ่มต้นและค่าสิ้นสุดของกลุ่มจะระบุเป็นประเภทค่าของเมตริกที่แสดง ตัวอย่างเช่น First Contentful Paint จะวัดเป็นมิลลิวินาทีและแสดงเป็นจำนวนเต็ม ดังนั้นกลุ่มเมตริกจะใช้ int32 สำหรับประเภทเริ่มต้นและสิ้นสุด อย่างไรก็ตาม Cumulative Layout Shift จะวัดเป็นทศนิยมแบบไม่มีหน่วยและแสดงเป็นทศนิยมที่เข้ารหัสเป็นสตริง ดังนั้นกลุ่มเมตริกจะใช้สตริงสำหรับประเภทค่า

{
  "start": value,
  "end": value,
  "density": number
}

เปอร์เซ็นไทล์

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

{
  "P75": value
}

เศษส่วน

Fractions มีเศษส่วนที่ติดป้ายกำกับซึ่งรวมกันได้ประมาณ 1 ป้ายกำกับแต่ละรายการจะอธิบายการโหลดหน้าเว็บในลักษณะหนึ่ง ดังนั้นเมตริกที่แสดงในลักษณะนี้จึงถือได้ว่าสร้างค่าที่แตกต่างกันแทนค่าตัวเลข และเศษส่วนจะแสดงความถี่ในการวัดค่าที่แตกต่างกันหนึ่งๆ

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

เช่นเดียวกับค่าความหนาแน่นในช่องฮิสโตแกรม fraction แต่ละค่าจะเป็นตัวเลข 0.0 <= value <= 1.0 และรวมกันได้ประมาณ 1.0

UrlNormalization

ออบเจ็กต์ที่แสดงถึงการดำเนินการปรับมาตรฐานที่ทำเพื่อปรับมาตรฐาน URL เพื่อให้มีโอกาสค้นหาสำเร็จมากขึ้น การเปลี่ยนแปลงเหล่านี้เป็นการเปลี่ยนแปลงพื้นฐานแบบอัตโนมัติที่เกิดขึ้นเมื่อการค้นหา url_pattern ที่ระบุล้มเหลว ระบบจะไม่จัดการการดำเนินการที่ซับซ้อน เช่น การติดตามการเปลี่ยนเส้นทาง

{
  "originalUrl": string,
  "normalizedUrl": string
}

ขีดจำกัดอัตรา

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