Google Analytics का इस्तेमाल करें

इस ट्यूटोरियल में, Google Analytics का इस्तेमाल करके अपने एक्सटेंशन के इस्तेमाल को ट्रैक करने का तरीका बताया गया है. आपको GitHub पर Google Analytics का एक वर्किंग सैंपल मिल सकता है. इसमें google-analytics.js में Google Analytics से जुड़ा सारा कोड शामिल है.

ज़रूरी शर्तें

इस ट्यूटोरियल में यह माना गया है कि आपको Chrome एक्सटेंशन लिखने के बारे में जानकारी है. अगर आपको एक्सटेंशन लिखने के तरीके के बारे में जानकारी चाहिए, तो शुरू करने से जुड़ा ट्यूटोरियल पढ़ें.

अपने एक्सटेंशन को ट्रैक करने के लिए, आपको Google Analytics खाता भी सेट अप करना होगा. ध्यान दें कि खाता सेट अप करते समय, वेबसाइट के यूआरएल फ़ील्ड में किसी भी वैल्यू का इस्तेमाल किया जा सकता है. ऐसा इसलिए, क्योंकि आपके एक्सटेंशन का अपना कोई यूआरएल नहीं होगा.

Google Analytics मेज़रमेंट प्रोटोकॉल का इस्तेमाल करना

Manifest V3 के बाद से, Chrome एक्सटेंशन को रिमोट होस्ट किए गए कोड को एक्ज़ीक्यूट करने की अनुमति नहीं है. इसका मतलब है कि आपको एक्सटेंशन इवेंट को ट्रैक करने के लिए, Google Analytics मेज़रमेंट प्रोटोकॉल का इस्तेमाल करना होगा. मेज़रमेंट प्रोटोकॉल की मदद से, एचटीटीपी अनुरोधों के ज़रिए सीधे Google Analytics सर्वर पर इवेंट भेजे जा सकते हैं. इस तरीके का एक फ़ायदा यह है कि इसकी मदद से, अपने एक्सटेंशन में हर जगह से आंकड़ों के इवेंट भेजे जा सकते हैं. इसमें आपका सर्विस वर्कर भी शामिल है.

एपीआई क्रेडेंशियल सेट अप करना

Google Analytics को इवेंट भेजने के लिए, आपको api_secret और measurement_id की ज़रूरत होती है. मेज़रमेंट प्रोटोकॉल के सामान्य स्पेसिफ़िकेशन के बारे में ज़्यादा जानने के लिए, मेज़रमेंट प्रोटोकॉल के दस्तावेज़ पढ़ें.

पहला चरण: कोई वेब डेटा स्ट्रीम बनाना

Chrome एक्सटेंशन को वेब एनवायरमेंट के तौर पर ट्रैक किया जाता है. इसलिए, आपको अपनी Google Analytics प्रॉपर्टी में वेबसाइट डेटा स्ट्रीम सेट अप करनी होगी:

1. Google Analytics के एडमिन पेज पर जाएं.
2. प्रॉपर्टी कॉलम में, डेटा कलेक्शन और डेटा में बदलाव पर क्लिक करें. इसके बाद, डेटा स्ट्रीम चुनें.
3. स्ट्रीम जोड़ें पर क्लिक करें. इसके बाद, वेब पर क्लिक करें.
4. वेबसाइट का यूआरएल फ़ील्ड में कोई प्लेसहोल्डर यूआरएल डालें. उदाहरण के लिए, https://extension या आपके एक्सटेंशन का Chrome Web Store यूआरएल.
5. स्ट्रीम का नाम डालें. उदाहरण के लिए, My Chrome Extension.
6. स्ट्रीम बनाएं पर क्लिक करें.

बन जाने के बाद, आपका मेज़रमेंट आईडी (जो G-XXXXXXXXXX जैसा दिखता है) स्ट्रीम की जानकारी वाले पेज पर सबसे ऊपर दिखेगा.

दूसरा चरण: मेज़रमेंट प्रोटोकॉल एपीआई सीक्रेट जनरेट करना

मेज़रमेंट प्रोटोकॉल के लिए ज़रूरी api_secret जनरेट करने के लिए, अभी-अभी बनाई गई वेब डेटा स्ट्रीम की सेटिंग पर जाएं:

1. एडमिन > डेटा कलेक्शन और डेटा में बदलाव > डेटा स्ट्रीम पर जाएं. इसके बाद, अपनी वेब डेटा स्ट्रीम चुनें.

2. इवेंट सेक्शन में, मेज़रमेंट प्रोटोकॉल एपीआई सीक्रेट पर क्लिक करें.

3. अगर प्रॉम्प्ट मिलता है, तो मेज़रमेंट प्रोटोकॉल की शर्तें पढ़ें और उन्हें स्वीकार करें.

4. बनाएं पर क्लिक करें.

5. अपने सीक्रेट के लिए कोई निकनेम डालें. उदाहरण के लिए, Chrome Extension Secret) और सीक्रेट जनरेट करने के लिए, बनाएं पर क्लिक करें.

6. जनरेट की गई सीक्रेट वैल्यू को कॉपी करें.

client_id जनरेट करें

दूसरा चरण, किसी डिवाइस/उपयोगकर्ता के लिए यूनीक आइडेंटिफ़ायर जनरेट करना है. इसे client_id कहा जाता है. जब तक एक्सटेंशन किसी उपयोगकर्ता के ब्राउज़र पर इंस्टॉल रहता है, तब तक आईडी एक ही रहना चाहिए. यह कोई भी स्ट्रिंग हो सकती है, लेकिन यह क्लाइंट के लिए यूनीक होनी चाहिए. client_id को chrome.storage.local में सेव करें, ताकि एक्सटेंशन इंस्टॉल रहने तक यह वैल्यू वही बनी रहे.

chrome.storage.local का इस्तेमाल करने के लिए, आपकी मेनिफ़ेस्ट फ़ाइल में storage अनुमति होनी चाहिए:

manifest.json:

{
  …
  "permissions": ["storage"],
  …
}

इसके बाद, client_id को सेव करने के लिए chrome.storage.local का इस्तेमाल किया जा सकता है:

function getRandomId() {
  const digits = '123456789'.split('');
  let result = '';

  for (let i = 0; i < 10; i++) {
    result += digits[Math.floor(Math.random() * 9)];
  }

  return result;
}

async function getOrCreateClientId() {
  const result = await chrome.storage.local.get('clientId');
  let clientId = result.clientId;
  if (!clientId) {
    // Generate a unique client ID, the actual value is not relevant. We use
    // the <number>.<number> format since this is typical for GA client IDs.
    const unixTimestampSeconds = Math.floor(new Date().getTime() / 1000);
    clientId = `${getRandomId()}.${unixTimestampSeconds}`;
    await chrome.storage.local.set({clientId});
  }
  return clientId;
}

Analytics इवेंट भेजना

एपीआई क्रेडेंशियल और client_id की मदद से, fetch अनुरोध का इस्तेमाल करके, Google Analytics को इवेंट भेजा जा सकता है:

const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;

fetch(
  `${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: 'POST',
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: 'button_clicked',
          params: {
            id: 'my-button',
          },
        },
      ],
    }),
  }
);

इससे button_clicked इवेंट भेजा जाता है. यह आपकी Google Analytics की इवेंट रिपोर्ट में दिखेगा. अगर आपको अपने इवेंट, Google Analytics की रीयलटाइम रिपोर्ट में देखने हैं, तो आपको दो और पैरामीटर देने होंगे: session_id और engagement_time_msec.

सुझाए गए पैरामीटर session_id और engagement_time_msec का इस्तेमाल करें

session_id और engagement_time_msec, Google Analytics मेज़रमेंट प्रोटोकॉल का इस्तेमाल करते समय सुझाए गए पैरामीटर हैं. ऐसा इसलिए, क्योंकि उपयोगकर्ता की गतिविधि को रीयलटाइम जैसी स्टैंडर्ड रिपोर्ट में दिखाने के लिए इनकी ज़रूरत होती है.

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

सामान्य वेबसाइटों के उलट, Chrome एक्सटेंशन में उपयोगकर्ता सेशन के बारे में साफ़ तौर पर नहीं बताया जाता है. इसलिए, आपको अपने एक्सटेंशन में यह तय करना होगा कि उपयोगकर्ता सेशन का क्या मतलब है. उदाहरण के लिए, हर नए उपयोगकर्ता इंटरैक्शन को एक नया सेशन माना जा सकता है. ऐसे में, हर इवेंट के लिए एक नया सेशन आईडी जनरेट किया जा सकता है. जैसे, टाइमस्टैंप का इस्तेमाल करना.

यहां दिए गए उदाहरण में, एक ऐसा तरीका दिखाया गया है जिससे 30 मिनट तक कोई इवेंट रिपोर्ट न होने पर, नया सेशन टाइम आउट हो जाएगा. इस समय को अपने एक्सटेंशन के उपयोगकर्ता के व्यवहार के हिसाब से बदला जा सकता है. इस उदाहरण में, ब्राउज़र चालू होने पर ऐक्टिव सेशन को सेव करने के लिए chrome.storage.session का इस्तेमाल किया जाता है. हम सेशन के साथ-साथ, इवेंट के ट्रिगर होने का पिछला समय भी सेव करते हैं. इससे हमें यह पता चलता है कि चालू सेशन की समयसीमा खत्म हो गई है या नहीं:

const SESSION_EXPIRATION_IN_MIN = 30;

async function getOrCreateSessionId() {
  // Store session in memory storage
  let {sessionData} = await chrome.storage.session.get('sessionData');
  // Check if session exists and is still valid
  const currentTimeInMs = Date.now();
  if (sessionData && sessionData.timestamp) {
    // Calculate how long ago the session was last updated
    const durationInMin = (currentTimeInMs - sessionData.timestamp) / 60000;
    // Check if last update lays past the session expiration threshold
    if (durationInMin > SESSION_EXPIRATION_IN_MIN) {
      // Delete old session id to start a new session
      sessionData = null;
    } else {
      // Update timestamp to keep session alive
      sessionData.timestamp = currentTimeInMs;
      await chrome.storage.session.set({sessionData});
    }
  }
  if (!sessionData) {
    // Create and store a new session
    sessionData = {
      session_id: currentTimeInMs.toString(),
      timestamp: currentTimeInMs.toString(),
    };
    await chrome.storage.session.set({sessionData});
  }
  return sessionData.session_id;
}

यहां दिए गए उदाहरण में, session_id और engagement_time_msec को, बटन क्लिक करने के पिछले इवेंट के अनुरोध में जोड़ा गया है. engagement_time_msec के लिए, सबसे अच्छा तरीका यह है कि पिछले इवेंट के बाद से बीता हुआ समय बताया जाए. हालांकि, अगर ऐसा करना मुमकिन नहीं है, तो 100 ms की डिफ़ॉल्ट वैल्यू दी जा सकती है.

const GA_ENDPOINT = "https://www.google-analytics.com/mp/collect";
const MEASUREMENT_ID = `G-...`;
const API_SECRET = `...`;
const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;

fetch(
`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "button_clicked",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            id: "my-button",
          },
        },
      ],
    }),
  }
);

Google Analytics की रीयलटाइम रिपोर्ट में, इवेंट इस तरह दिखेगा.

पॉप-अप, साइड पैनल, और एक्सटेंशन पेजों में पेज व्यू ट्रैक करना

Google Analytics मेज़रमेंट प्रोटोकॉल, पेज व्यू को ट्रैक करने के लिए खास page_view इवेंट का इस्तेमाल करता है. इसका इस्तेमाल, नए टैब में आपके डायलॉग बॉक्स, मेन्यू पेजों, साइड पैनल, और एक्सटेंशन पेजों पर आने वाले लोगों को ट्रैक करने के लिए करें. page_view इवेंट के लिए, page_title और page_location पैरामीटर भी ज़रूरी होते हैं. यहां दिए गए उदाहरण में, एक्सटेंशन मेन्यू के लिए दस्तावेज़ load इवेंट पर पेज व्यू इवेंट ट्रिगर किया गया है:

popup.js:

window.addEventListener("load", async () => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          name: "page_view",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            page_title: document.title,
            page_location: document.location.href
          },
        },
      ],
    }),
  });
});

popup.js स्क्रिप्ट को आपके पॉप-अप की एचटीएमएल फ़ाइल में इंपोर्ट किया जाना चाहिए. साथ ही, इसे किसी भी अन्य स्क्रिप्ट के चलने से पहले चलना चाहिए:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Analytics Demo Popup</title>
    <script src="./popup.js" type="module"></script>
  </head>
  <body>
    <h1>Analytics Demo</h1>
  </body>
</html>

पॉप-अप व्यू, Google Analytics की रीयलटाइम रिपोर्ट में किसी अन्य पेज व्यू की तरह दिखेगा:

सर्विस वर्कर में आंकड़ों से जुड़े इवेंट ट्रैक करना

Google Analytics मेज़रमेंट प्रोटोकॉल का इस्तेमाल करके, एक्सटेंशन सर्विस वर्कर में Analytics इवेंट को ट्रैक किया जा सकता है. उदाहरण के लिए, अपने सर्विस वर्कर में unhandledrejection event को सुनकर, Google Analytics में किसी भी ऐसे अपवाद को लॉग किया जा सकता है जिसे पकड़ा नहीं गया है. इससे उन समस्याओं को डीबग करने में काफ़ी मदद मिल सकती है जिनकी शिकायत आपके उपयोगकर्ता कर सकते हैं.

service-worker.js:

addEventListener("unhandledrejection", async (event) => {
  fetch(`${GA_ENDPOINT}?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
  {
    method: "POST",
    body: JSON.stringify({
      client_id: await getOrCreateClientId(),
      events: [
        {
          // Note: 'error' is a reserved event name and cannot be used
          // see https://developers.google.com/analytics/devguides/collection/protocol/ga4/reference?client_type=gtag#reserved_names
          name: "extension_error",
          params: {
            session_id: await getOrCreateSessionId(),
            engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
            message: event.reason.message,
            stack: event.reason.stack,
          },
        },
      ],
    }),
  });
});

अब आपको Google Analytics की रिपोर्ट में गड़बड़ी वाला इवेंट दिखेगा:

डीबग करना

Google Analytics, आपके एक्सटेंशन में Analytics इवेंट को डीबग करने के लिए दो काम की सुविधाएं उपलब्ध कराता है:

1. एक खास डीबगिंग एंडपॉइंट https://www.google-analytics.com**/debug**/mp/collect, जो इवेंट की परिभाषाओं में मौजूद किसी भी गड़बड़ी की सूचना देगा.
2. Google Analytics की रीयलटाइम रिपोर्ट, जिसमें इवेंट के डेटा को रीयलटाइम में दिखाया जाएगा.