CrUX एपीआई

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

इसे आज़माएं!

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

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

CrUX API पासकोड

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

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

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

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

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

उदाहरण के तौर पर दी गई क्वेरी देखें.

डेटा मॉडल

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

रिकॉर्ड करें

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

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

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

शुरुआत की जगह

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

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

इसका मतलब है कि ऑरिजिन को http://www.example.com पर सेट करके, Chrome UX Report से क्वेरी करने पर, 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 डेटा इकट्ठा किया गया था. हालांकि, यह ज़रूरी नहीं है कि डेटा उसी समयावधि के बारे में बताता हो.

क्वेरी के उदाहरण

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

अगर formFactor की कोई वैल्यू नहीं दी जाती है, तो सभी फ़ॉर्म फ़ैक्टर के लिए वैल्यू इकट्ठा की जाएंगी.

ज़्यादा क्वेरी के उदाहरणों के लिए, Chrome UX Report API का इस्तेमाल करना लेख पढ़ें.

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

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

रोलिंग औसत

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

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

या

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

बिन

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

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