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

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

Rick Viscomi

Shane Exterkamp

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

यह एपीआई, डेवलपर को CrUX डेटा का आसान, तेज़, और बेहतर ऐक्सेस देने के मकसद से बनाया गया है. CrUX API, सिर्फ़ फ़ील्ड उपयोगकर्ता अनुभव के डेटा की रिपोर्ट करता है, जबकि मौजूदा PageSpeed Insights API में ऐसा होता है. इसमें Lighthouse की परफ़ॉर्मेंस के ऑडिट से मिलने वाला lab डेटा भी शामिल होता है. 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"}'

ध्यान दें: सभी एपीआई अनुरोधों में key पैरामीटर के लिए एक वैल्यू दी जानी चाहिए—[YOUR_API_KEY] पिछले उदाहरण में, इसे प्लेसहोल्डर के तौर पर ही छोड़ दिया गया है. CrUX API दस्तावेज़ में बताए गए तरीके से, अपनी निजी CrUX API कुंजी पाएं.

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 एपीआई में, किसी ऑरिजिन के लिए कोई डेटा नहीं होता, तो यह 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% "अच्छा" अनुभव है. साथ ही, इसका 1,947 मिलीसेकंड का 75वां पर्सेंटाइल है, जो कि पूरे ऑरिजिन में डिस्ट्रिब्यूशन से थोड़ा बेहतर है.

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

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/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'first_input_delay',
    '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}).`)
  });
}

अहम जानकारी: एपीआई को एक बार में सिर्फ़ एक ऑरिजिन या यूआरएल का इस्तेमाल करके कॉल किया जा सकता है. एक से ज़्यादा वेबसाइटों या पेजों का आकलन करने के लिए, एपीआई को अलग-अलग कॉल करें.

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

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of first_input_delay passes the Core Web Vitals "good" threshold (100).
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 एलान फ़ोरम की सदस्यता लें या हमें @ChromeUXreport पर Twitter पर फ़ॉलो करें.