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

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

Rick Viscomi

Shane Exterkamp

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

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

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

{"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',
    '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}).`)
  });
}

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

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 पर फ़ॉलो करें.