CrUX एपीआई

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

इसे आज़माएं!

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

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

CrUX API पासकोड

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_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 डेटासेट की ओर से हर महीने की रिपोर्ट को एग्रीगेट करने के तरीके जैसा ही है.

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

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

स्कीमा

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

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

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

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

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