CrUX API इस्तेमाल करने का तरीका

Chrome UX Report API का इस्तेमाल करने का तरीका जानें, ताकि लाखों वेबसाइटों पर उपयोगकर्ता अनुभव के डेटा को ऐक्सेस किया जा सके.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Chrome UX रिपोर्ट (CrUX) डेटासेट से पता चलता है कि असल दुनिया में Chrome का इस्तेमाल करने वाले उपयोगकर्ताओं को वेब पर मौजूद लोकप्रिय साइटों पर कैसा अनुभव मिलता है. BigQuery पर क्वेरी करने लायक डेटासेट को पहली बार 2017 में रिलीज़ किया गया था. इसके बाद, CrUX का फ़ील्ड डेटा, PageSpeed Insights, CrUX डैशबोर्ड, और Search Console की वेबसाइट की परफ़ॉर्मेंस की अहम जानकारी वाली रिपोर्ट जैसे डेवलपर टूल में इंटिग्रेट किया गया है. इससे डेवलपर, असल उपयोगकर्ता अनुभव को मेज़र और मॉनिटर कर सकते हैं. इस टूल की कमी इस वजह से थी, क्योंकि यह प्रोग्राम के हिसाब से CrUX डेटा को बिना किसी शुल्क के और RESTful तरीके से ऐक्सेस करने की सुविधा देता है. इस अंतर को कम करने के लिए, हमें यह बताते हुए खुशी हो रही है कि हमने नया Chrome UX Report API रिलीज़ किया है!

इस एपीआई को इस मकसद से बनाया गया है कि डेवलपर, CrUX डेटा को आसानी से, तेज़ी से, और पूरी जानकारी के साथ ऐक्सेस कर सकें. CrUX API, सिर्फ़ फ़ील्ड उपयोगकर्ता अनुभव का डेटा दिखाता है. यह मौजूदा PageSpeed Insights API से अलग है, जो Lighthouse की परफ़ॉर्मेंस की जांच से मिले लैब डेटा को भी दिखाता है. CrUX API को बेहतर बनाया गया है. यह उपयोगकर्ता अनुभव का डेटा तुरंत दिखा सकता है. इसलिए, यह रीयल-टाइम ऑडिटिंग ऐप्लिकेशन के लिए सबसे सही है.

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

आइए, इस बारे में ज़्यादा जानें और इसका इस्तेमाल करने का तरीका जानें!

इस पेज पर एपीआई आज़माएं

इसे आज़माएं!

ऑरिजिन डेटा की क्वेरी

CrUX डेटासेट में मौजूद ऑरिजिन में, पेज-लेवल पर मिलने वाले सभी अनुभव शामिल होते हैं. यहां दिए गए उदाहरण में, कमांड लाइन पर cURL का इस्तेमाल करके, किसी ऑरिजिन के उपयोगकर्ता अनुभव के डेटा के लिए CrUX API से क्वेरी करने का तरीका बताया गया है.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"origin": "https://web.dev"}'

curl निर्देश तीन हिस्सों में होता है:

  1. एपीआई का यूआरएल एंडपॉइंट, जिसमें कॉलर की निजी एपीआई पासकोड शामिल है.
  2. Content-Type: application/json हेडर, जो बताता है कि अनुरोध के मुख्य हिस्से में JSON है.
  3. JSON कोड में बदला गया https://web.dev ऑरिजिन की जानकारी देने वाला रिक्वेस्ट बॉडी.

JavaScript में भी यही काम करने के लिए, CrUXApiUtil यूटिलिटी का इस्तेमाल करें. यह एपीआई कॉल करता है और डिकोड किया गया रिस्पॉन्स दिखाता है. इतिहास और एक साथ कई अनुरोध करने की सुविधा के साथ-साथ ज़्यादा सुविधाओं के लिए, हमारा GitHub वैरिएंट भी देखें.

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

[YOUR_API_KEY] को अपनी कुंजी से बदलें. इसके बाद, CrUXApiUtil.query फ़ंक्शन को कॉल करें और request body ऑब्जेक्ट को पास करें.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

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

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            "density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

histogram ऑब्जेक्ट की start और end प्रॉपर्टी, किसी मेट्रिक के लिए उपयोगकर्ताओं को मिलने वाली वैल्यू की रेंज दिखाती हैं. density प्रॉपर्टी से उस रेंज में उपयोगकर्ता अनुभव का अनुपात पता चलता है. इस उदाहरण में, web.dev के सभी पेजों पर 79% एलसीपी उपयोगकर्ता अनुभव 2,500 मिलीसेकंड से कम हैं. यह एलसीपी का "अच्छा" थ्रेशोल्ड है. percentiles.p75 वैल्यू का मतलब है कि इस डिस्ट्रिब्यूशन में 75% उपयोगकर्ता अनुभव 2,216 मिलीसेकंड से कम हैं. रिस्पॉन्स बॉडी दस्तावेज़ में, रिस्पॉन्स के स्ट्रक्चर के बारे में ज़्यादा जानें.

गड़बड़ियां

जब CrUX API के पास किसी ऑरिजिन का डेटा नहीं होता है, तो वह JSON में कोड किए गए गड़बड़ी के मैसेज के साथ जवाब देता है:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

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

गड़बड़ी
{"origin": "http://www.web.dev"}

इस ऑरिजिन में, http:// प्रोटोकॉल और www. सबडोमेन गलत तरीके से शामिल है.

काम हो गया
{"origin": "https://web.dev"}

इस ऑरिजिन को सार्वजनिक तौर पर ऐक्सेस किया जा सकता है.

अगर अनुरोध किया गया ऑरिजिन, नेविगेट किया जा सकने वाला वर्शन है, तो यह गड़बड़ी तब भी हो सकती है, जब ऑरिजिन में सैंपल की संख्या काफ़ी न हो. डेटासेट में शामिल सभी ऑरिजिन और यूआरएल में, उपयोगकर्ताओं की पहचान छिपाने के लिए ज़रूरत के मुताबिक सैंपल होने चाहिए. इसके अलावा, ऑरिजिन और यूआरएल ऐसे होने चाहिए जिन्हें सार्वजनिक तौर पर इंडेक्स किया जा सके. डेटासेट में वेबसाइटों को शामिल करने के तरीके के बारे में ज़्यादा जानने के लिए, CrUX का तरीका देखें.

यूआरएल के डेटा की क्वेरी

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

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

यह cURL कमांड, ऑरिजिन के उदाहरण से मिलता-जुलता है. हालांकि, अनुरोध बॉडी में url पैरामीटर का इस्तेमाल करके, खोजे जाने वाले पेज की जानकारी दी जाती है.

JavaScript में CrUX API से यूआरएल डेटा की क्वेरी करने के लिए, अनुरोध बॉडी में url पैरामीटर का इस्तेमाल करके CrUXApiUtil.query फ़ंक्शन को कॉल करें.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

अगर CrUX डेटासेट में इस यूआरएल का डेटा मौजूद है, तो एपीआई JSON में कोड में बदला गया जवाब दिखाएगा. उदाहरण के लिए

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

नतीजों से पता चलता है कि https://web.dev/fast/ के 85% उपयोगकर्ताओं को "अच्छा" एलसीपी अनुभव मिला. साथ ही, 75वां पर्सेंटाइल 1,947 मिलीसेकंड का रहा, जो ओरिजिन के हिसाब से डिस्ट्रिब्यूशन से थोड़ा बेहतर है.

यूआरएल को नॉर्मलाइज़ करना

CrUX API, अनुरोध किए गए यूआरएल को सामान्य बना सकता है, ताकि वे जाने-पहचाने यूआरएल की सूची से बेहतर तरीके से मैच कर सकें. उदाहरण के लिए, यूआरएल https://web.dev/fast/#measure-performance-in-the-field के लिए क्वेरी करने पर, सामान्य बनाने की वजह से https://web.dev/fast/ का डेटा दिखेगा. ऐसा होने पर, रिस्पॉन्स में urlNormalizationDetails ऑब्जेक्ट शामिल किया जाएगा.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

CrUX के दस्तावेज़ में, यूआरएल को सामान्य बनाने के बारे में ज़्यादा जानें.

डिवाइस के नाप या आकार के हिसाब से क्वेरी

वेबसाइट के ऑप्टिमाइज़ेशन, नेटवर्क की स्थिति, और उपयोगकर्ताओं के डिवाइसों के हिसाब से, उपयोगकर्ताओं को मिलने वाले अनुभव में काफ़ी अंतर हो सकता है. इन अंतरों को बेहतर तरीके से समझने के लिए, CrUX API के formFactor डाइमेंशन का इस्तेमाल करके, ऑरिजिन और यूआरएल की परफ़ॉर्मेंस पर ड्रिल-डाउन करें.

एपीआई में फ़ॉर्म फ़ैक्टर की तीन वैल्यू इस्तेमाल की जा सकती हैं: DESKTOP, PHONE, और TABLET. ऑरिजिन या यूआरएल के अलावा, रिक्वेस्ट बॉडी में इनमें से कोई एक वैल्यू डालें, ताकि नतीजों को सिर्फ़ उन उपयोगकर्ता अनुभवों तक सीमित किया जा सके. इस उदाहरण में, cURL का इस्तेमाल करके फ़ॉर्म फ़ैक्टर के हिसाब से एपीआई से क्वेरी करने का तरीका बताया गया है.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

JavaScript का इस्तेमाल करके, फ़ॉर्म फ़ैक्टर के हिसाब से डेटा के लिए CrUX API से क्वेरी करने के लिए, अनुरोध बॉडी में url और formFactor पैरामीटर का इस्तेमाल करके CrUXApiUtil.query फ़ंक्शन को कॉल करें.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

formFactor पैरामीटर को छोड़ने का मतलब है कि सभी फ़ॉर्म फ़ैक्टर के लिए डेटा का अनुरोध किया जा रहा है.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

जवाब के key फ़ील्ड में, formFactor अनुरोध कॉन्फ़िगरेशन दिखेगा. इससे यह पुष्टि की जा सकेगी कि सिर्फ़ फ़ोन पर मिलने वाले अनुभव शामिल किए गए हैं.

पिछले सेक्शन में बताया गया था कि इस पेज पर 85% उपयोगकर्ताओं को "अच्छा" एलसीपी मिला था. इसकी तुलना, फ़ोन पर मिलने वाले अनुभवों से करें. इनमें से सिर्फ़ 78% अनुभवों को "अच्छा" माना जाता है. फ़ोन पर 75वें पर्सेंटाइल की स्पीड भी धीमी हुई है. यह 1,947 मिलीसेकंड से बढ़कर 2,366 मिलीसेकंड हो गई है. फ़ॉर्म फ़ैक्टर के हिसाब से सेगमेंट करने से, उपयोगकर्ता अनुभव में ज़्यादा अंतर दिख सकता है.

वेबसाइट की परफ़ॉर्मेंस की अहम जानकारी देने वाली मेट्रिक का आकलन करना

वेबसाइट की परफ़ॉर्मेंस की जानकारी प्रोग्राम, ऐसे टारगेट तय करता है जिनसे यह तय करने में मदद मिलती है कि किसी उपयोगकर्ता अनुभव या अनुभवों के डिस्ट्रिब्यूशन को "अच्छा" माना जा सकता है या नहीं. नीचे दिए गए उदाहरण में, हम CrUX API और CrUXApiUtil.query फ़ंक्शन का इस्तेमाल करके यह आकलन करते हैं कि किसी वेब पेज पर, वेबसाइट की परफ़ॉर्मेंस की अहम जानकारी देने वाली मेट्रिक (एलसीपी, आईएनपी, सीएलएस) का डिस्ट्रिब्यूशन "अच्छा" है या नहीं.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the "good" threshold.
    const passes = p75 < threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

नतीजों से पता चलता है कि यह पेज, तीनों मेट्रिक के लिए Core Web Vitals के आकलन में पास हो गया है.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

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

आगे क्या करना है?

CrUX API के शुरुआती वर्शन में शामिल सुविधाएं, CrUX की मदद से मिलने वाली अहम जानकारी के बारे में सिर्फ़ जानकारी देती हैं. BigQuery पर CrUX डेटासेट के उपयोगकर्ता, कुछ बेहतर सुविधाओं के बारे में जानते होंगे. इनमें ये शामिल हैं:

  • अन्य मेट्रिक
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • अन्य डाइमेंशन
    • month
    • country
    • effective connection type (ईसीटी)
  • ज़्यादा जानकारी
    • ज़्यादा जानकारी वाले हिस्टोग्राम
    • ज़्यादा पर्सेंटाइल

अपना एपीआई पासकोड पाने और ज़्यादा उदाहरण वाले ऐप्लिकेशन के बारे में जानने के लिए, CrUX API के आधिकारिक दस्तावेज़ देखें. हमें उम्मीद है कि आप इसे आज़माएंगे. अगर आपका कोई सवाल या सुझाव है, तो हमें बताएं. इसके लिए, CrUX के चर्चा फ़ोरम पर जाएं. CrUX API के लिए, हमने जो भी योजना बनाई है उसके बारे में अप-टू-डेट रहने के लिए, CrUX के एलान वाले फ़ोरम की सदस्यता लें या हमें Twitter पर @ChromeUXReport पर फ़ॉलो करें.