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

ซึ่งหมายความว่าเมื่อค้นหารายงาน UX ของ Chrome โดยตั้งค่าต้นทางเป็น 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 เป็นเลขทศนิยมที่โค้ดเป็นสตริง จึงไม่ใช่ค่าทศนิยมและระบบจะรายงานเป็น 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_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 ในคำขอ)

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

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

Data Pipeline

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

ค่าเฉลี่ยต่อเนื่อง

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

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

ข้อมูลอัปเดตรายวัน

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

สคีมา

CrUX API มีปลายทางเดียวที่ยอมรับคำขอ POST HTTP 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 คือส่วนของข้อมูลที่แยกจากกันซึ่งครอบคลุมตั้งแต่ต้นจนจบ หรือหากไม่ได้ระบุจุดสิ้นสุด bin จะหมายถึงตั้งแต่ต้นจนบวกอนันต์

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

{
  "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 Cloud ซึ่งให้บริการโดยไม่มีค่าใช้จ่าย คุณดูขีดจํากัดนี้และการใช้งานปัจจุบันได้ในคอนโซล Google Cloud โควต้าจำนวนมากนี้น่าจะเพียงพอสำหรับ Use Case ส่วนใหญ่ และคุณไม่สามารถชำระเงินเพื่อเพิ่มโควต้าได้