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 นั้นๆ ลองดู http://www.example.com Sitemap ต้นฉบับอีกครั้ง

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