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

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Chrome UX Report (CrUX) डेटासेट से पता चलता है कि असल दुनिया में Chrome का इस्तेमाल करने वाले उपयोगकर्ताओं को वेब पर मौजूद लोकप्रिय साइटों पर कैसा अनुभव मिल रहा है. साल 2017 में, जब क्वेरी किए जा सकने वाले डेटासेट को पहली बार BigQuery पर रिलीज़ किया गया था, तब से CrUX के फ़ील्ड डेटा को डेवलपर टूल में इंटिग्रेट किया गया है. जैसे, PageSpeed Insights और 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 फ़ंक्शन को कॉल करें और अनुरोध का मुख्य हिस्सा ऑब्जेक्ट पास करें.

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

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

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

यह कर्ल कमांड, ऑरिजिन के उदाहरण जैसी ही है. हालांकि, अनुरोध के मुख्य हिस्से में 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
  • ज़्यादा जानकारी
    • ज़्यादा जानकारी वाले हिस्टोग्राम
    • ज़्यादा पर्सेंटाइल

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