CrUX एपीआई

CrUX API, पेज और ऑरिजिन के हिसाब से, असल उपयोगकर्ता अनुभव के एग्रीगेट किए गए डेटा को कम इंतज़ार के समय में ऐक्सेस करने की सुविधा देता है.

इसे आज़माएं!

इस्तेमाल का सामान्य उदाहरण

CrUX API की मदद से, किसी खास यूआरआई के लिए उपयोगकर्ता अनुभव की मेट्रिक के बारे में क्वेरी की जा सकती है. जैसे, "https://example.com ऑरिजिन के लिए मेट्रिक पाएं."

CrUX एपीआई पासकोड

CrUX API का इस्तेमाल करने के लिए, Google Cloud एपीआई पासकोड की ज़रूरत होती है. इसे Chrome UX Report API के इस्तेमाल के लिए उपलब्ध कराया जाता है.

एपीआई पासकोड पाना और उसका इस्तेमाल करना

इसके अलावा, क्रेडेंशियल पेज पर जाकर भी एक एपीआई पासकोड बनाया जा सकता है.

एपीआई पासकोड मिलने के बाद, आपका ऐप्लिकेशन सभी अनुरोध यूआरएल में क्वेरी पैरामीटर key=yourAPIKey जोड़ सकता है.

एपीआई पासकोड को यूआरएल में एम्बेड करना सुरक्षित है. इसके लिए, किसी एन्कोडिंग की ज़रूरत नहीं होती.

क्वेरी के उदाहरण देखें.

डेटा मॉडल

इस सेक्शन में, अनुरोधों और जवाबों में मौजूद डेटा के स्ट्रक्चर के बारे में बताया गया है.

रिकॉर्ड करें

किसी पेज या साइट के बारे में अलग-अलग जानकारी. किसी रिकॉर्ड में, किसी आइडेंटिफ़ायर और डाइमेंशन के खास कॉम्बिनेशन के लिए डेटा हो सकता है. किसी रिकॉर्ड में एक या उससे ज़्यादा मेट्रिक का डेटा हो सकता है.

आइडेंटिफ़ायर

आइडेंटिफ़ायर से पता चलता है कि किन रिकॉर्ड को देखना चाहिए. CrUX में, ये आइडेंटिफ़ायर वेबपेज और वेबसाइटें होती हैं.

शुरुआत की जगह

जब आइडेंटिफ़ायर कोई ऑरिजिन होता है, तो उस ऑरिजिन के सभी पेजों का डेटा एक साथ एग्रीगेट किया जाता है. उदाहरण के लिए, मान लें कि http://www.example.com ऑरिजिन में इस साइटमैप के मुताबिक पेज थे:

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

इसका मतलब है कि अगर Chrome के लिए उपयोगकर्ता अनुभव से जुड़ी रिपोर्ट में, ऑरिजिन को http://www.example.com पर सेट करके क्वेरी की जाती है, तो http://www.example.com/, http://www.example.com/foo.html, और http://www.example.com/bar.html का डेटा एक साथ इकट्ठा करके दिखाया जाएगा. ऐसा इसलिए, क्योंकि ये सभी पेज उस ऑरिजिन के तहत आते हैं.

यूआरएल

अगर आइडेंटिफ़ायर कोई यूआरएल है, तो सिर्फ़ उस यूआरएल का डेटा दिखेगा. http://www.example.com ऑरिजिन के साइटमैप को फिर से देखें:

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

अगर आइडेंटिफ़ायर को http://www.example.com/foo.html की वैल्यू वाले यूआरएल पर सेट किया जाता है, तो सिर्फ़ उस पेज का डेटा दिखेगा.

आयाम

डाइमेंशन, डेटा के उस खास ग्रुप की पहचान करते हैं जिसके लिए रिकॉर्ड को एग्रीगेट किया जा रहा है. उदाहरण के लिए, PHONE का फ़ॉर्म फ़ैक्टर यह बताता है कि रिकॉर्ड में, मोबाइल डिवाइस पर लोड हुए पेज की जानकारी शामिल है. हर डाइमेंशन में कुछ वैल्यू होंगी. अगर किसी डाइमेंशन की जानकारी नहीं दी जाती है, तो इसका मतलब है कि उस डाइमेंशन को सभी वैल्यू के साथ एग्रीगेट किया गया है. उदाहरण के लिए, डिवाइस का नाप या आकार तय न करने का मतलब है कि रिकॉर्ड में, किसी भी डिवाइस पर लोड होने वाले पेज की जानकारी शामिल है.

डिवाइस का नाप या आकार

असली उपयोगकर्ता ने पेज पर जाने के लिए किस डिवाइस क्लास का इस्तेमाल किया. यह डिवाइस की एक सामान्य क्लास है, जिसे PHONE, TABLET, और DESKTOP में बांटा गया है.

मेट्रिक

हम मेट्रिक को हिस्टोग्राम, पर्सेंटाइल, और फ़्रैक्शन में सांख्यिकीय एग्रीगेशन के तौर पर रिपोर्ट करते हैं.

फ़्लोटिंग पॉइंट वैल्यू को दशमलव के बाद चार अंकों तक राउंड किया जाता है. ध्यान दें कि cumulative_layout_shift मेट्रिक, स्ट्रिंग के तौर पर एन्कोड किए गए डबल डेटा टाइप होते हैं. इसलिए, इन्हें फ़्लोट नहीं माना जाता और स्ट्रिंग में दशमलव के बाद दो अंकों तक रिपोर्ट किया जाता है.

हिस्टोग्राम

जब मेट्रिक को हिस्टोग्राम में दिखाया जाता है, तो हम उस मेट्रिक के लिए खास रेंज में आने वाले पेज लोड का प्रतिशत दिखाते हैं.

उदाहरण के तौर पर, किसी मेट्रिक के लिए तीन बिन वाला हिस्टोग्राम इस तरह दिखता है:

{
  "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 ऑब्जेक्ट के तौर पर सबमिट किया जाता है. इसके लिए, https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" पर पोस्ट अनुरोध का इस्तेमाल किया जाता है. साथ ही, क्वेरी डेटा को पोस्ट बॉडी में JSON ऑब्जेक्ट के तौर पर सबमिट किया जाता है:

{
  "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"]}'

एपीआई की मदद से, पेज-लेवल का डेटा उपलब्ध होता है. इसके लिए, क्वेरी में origin के बजाय url प्रॉपर्टी को पास करना होगा:

{
  "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 के लिए उपयोगकर्ता अनुभव से जुड़ी रिपोर्ट API का इस्तेमाल करना लेख पढ़ें.

डेटा पाइपलाइन

CrUX डेटासेट को एक पाइपलाइन के ज़रिए प्रोसेस किया जाता है. इससे डेटा को इकट्ठा, एग्रीगेट, और फ़िल्टर किया जाता है. इसके बाद, एपीआई का इस्तेमाल करके डेटा उपलब्ध कराया जाता है.

रोलिंग औसत

Chrome के लिए उपयोगकर्ता अनुभव से जुड़ी रिपोर्ट में मौजूद डेटा, एग्रीगेट की गई मेट्रिक का 28 दिनों का रोलिंग औसत होता है. इसका मतलब है कि Chrome के लिए उपयोगकर्ता अनुभव से जुड़ी रिपोर्ट में किसी भी समय दिखाया गया डेटा, असल में पिछले 28 दिनों का कुल डेटा होता है.

यह BigQuery पर CrUX डेटासेट की ओर से हर महीने की रिपोर्ट को एग्रीगेट करने के तरीके जैसा ही है.

रोज़ाना अपडेट होता है

यह डेटा हर दिन 04:00 यूटीसी के आस-पास अपडेट किया जाता है. अपडेट होने के समय के लिए, सेवा स्तर का कोई समझौता नहीं है. इसे हर दिन, जितना संभव हो सके उतनी बेहतर कोशिश के आधार पर चलाया जाता है.

स्कीमा

CrUX API के लिए एक ही एंडपॉइंट है, जो POST एचटीटीपी अनुरोधों को स्वीकार करता है. एपीआई, record दिखाता है. इसमें एक या उससे ज़्यादा metrics होते हैं. ये अनुरोध किए गए ऑरिजिन या पेज के परफ़ॉर्मेंस डेटा से जुड़े होते हैं.

एचटीटीपी अनुरोध

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

यह यूआरएल, 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.
}

उदाहरण के लिए, 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, वेब की परफ़ॉर्मेंस की किसी एक मेट्रिक के लिए, उपयोगकर्ता अनुभव के एग्रीगेट किए गए डेटा का सेट होता है. जैसे, साइट का पहला एलिमेंट लोड होने में लगने वाला समय. इसमें Chrome के असल इस्तेमाल की खास जानकारी देने वाला हिस्टोग्राम हो सकता है. यह हिस्टोग्राम, bins की सीरीज़, खास पर्सेंटाइल डेटा (जैसे, p75) या लेबल किए गए फ़्रैक्शन के तौर पर हो सकता है.

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

या

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

बिन

bin, डेटा का एक अलग हिस्सा होता है, जो शुरू से लेकर आखिर तक फैला होता है. अगर कोई आखिरी हिस्सा नहीं दिया गया है, तो यह शुरू से लेकर पॉज़िटिव इनफ़िनिटी तक फैला होता है.

बिन की शुरुआती और आखिरी वैल्यू, उस मेट्रिक की वैल्यू टाइप में दी जाती हैं जिसे वह दिखाता है. उदाहरण के लिए, साइट का पहला एलिमेंट लोड होने में लगने वाले समय को मिलीसेकंड में मेज़र किया जाता है और इंट के तौर पर दिखाया जाता है. इसलिए, इसकी मेट्रिक बिन, शुरू और खत्म होने के टाइप के लिए int32s का इस्तेमाल करेंगी. हालांकि, लेआउट शिफ़्ट होने में लगने वाले समय को बिना यूनिट वाले दशमलव में मेज़र किया जाता है. साथ ही, इसे स्ट्रिंग के तौर पर एन्कोड किए गए दशमलव के तौर पर दिखाया जाता है. इसलिए, इसकी मेट्रिक बिन अपनी वैल्यू टाइप के लिए स्ट्रिंग का इस्तेमाल करेंगी.

{
  "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_pattern को खोजने पर, उसके न मिलने की संभावना हो. रीडायरेक्ट को फ़ॉलो करने जैसी जटिल कार्रवाइयां नहीं की जाती हैं.

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

अनुरोध संख्या सीमित करना

CrUX API का इस्तेमाल करके, हर Google Cloud प्रोजेक्ट के लिए एक मिनट में 150 क्वेरी की जा सकती हैं. इसके लिए कोई शुल्क नहीं लिया जाता. इस सीमा और अपने मौजूदा इस्तेमाल को Google Cloud Console में देखा जा सकता है. यह कोटा ज़्यादातर मामलों के लिए काफ़ी है. साथ ही, कोटा बढ़ाने के लिए पैसे नहीं चुकाए जा सकते.