গুগল অ্যানালিটিক্স ব্যবহার করুন

এই টিউটোরিয়ালটিতে দেখানো হয়েছে কিভাবে গুগল অ্যানালিটিক্স ব্যবহার করে আপনার এক্সটেনশনের ব্যবহার ট্র্যাক করা যায়। আপনি গিটহাবে একটি কার্যকরী গুগল অ্যানালিটিক্স স্যাম্পল খুঁজে পাবেন, যেখানে google-analytics.js ফাইলটিতে গুগল অ্যানালিটিক্স সম্পর্কিত সমস্ত কোড অন্তর্ভুক্ত রয়েছে।

প্রয়োজনীয়তা

এই টিউটোরিয়ালটি ধরে নেয় যে আপনি ক্রোম এক্সটেনশন লিখতে পরিচিত। এক্সটেনশন কীভাবে লিখতে হয় সে সম্পর্কে আপনার তথ্যের প্রয়োজন হলে, ‘গেটিং স্টার্টেড’ টিউটোরিয়ালটি পড়ুন।

আপনার এক্সটেনশনটি ট্র্যাক করার জন্য আপনাকে অবশ্যই একটি গুগল অ্যানালিটিক্স অ্যাকাউন্ট তৈরি করতে হবে। মনে রাখবেন, অ্যাকাউন্টটি তৈরি করার সময় আপনি 'ওয়েবসাইটের ইউআরএল' (Website's URL) ফিল্ডে যেকোনো মান ব্যবহার করতে পারেন, কারণ আপনার এক্সটেনশনের নিজস্ব কোনো ইউআরএল থাকবে না।

গুগল অ্যানালিটিক্স মেজারমেন্ট প্রোটোকল ব্যবহার করুন

Manifest V3 থেকে, Chrome এক্সটেনশনগুলোকে রিমোট হোস্টেড কোড এক্সিকিউট করার অনুমতি দেওয়া হয় না । এর মানে হলো, এক্সটেনশন ইভেন্ট ট্র্যাক করার জন্য আপনাকে Google Analytics Measurement Protocol ব্যবহার করতে হবে। এই Measurement Protocol আপনাকে HTTP রিকোয়েস্টের মাধ্যমে সরাসরি Google Analytics সার্ভারে ইভেন্ট পাঠাতে দেয়। এই পদ্ধতির একটি সুবিধা হলো, এটি আপনাকে আপনার সার্ভিস ওয়ার্কার সহ এক্সটেনশনের যেকোনো জায়গা থেকে অ্যানালিটিক্স ইভেন্ট পাঠাতে দেয়।

এপিআই ক্রেডেনশিয়াল সেট আপ করুন

গুগল অ্যানালিটিক্সে ইভেন্ট পাঠাতে আপনার একটি api_secret এবং একটি measurement_id প্রয়োজন। মেজারমেন্ট প্রোটোকলের সাধারণ স্পেসিফিকেশন সম্পর্কে আরও জানতে মেজারমেন্ট প্রোটোকল ডকুমেন্টেশন অনুসরণ করুন।

ধাপ ১: একটি ওয়েব ডেটা স্ট্রিম তৈরি করুন

যেহেতু ক্রোম এক্সটেনশনগুলিকে ওয়েব পরিবেশ হিসাবে ট্র্যাক করা হয়, তাই আপনাকে আপনার গুগল অ্যানালিটিক্স প্রপার্টিতে একটি ওয়েব ডেটা স্ট্রিম সেট আপ করতে হবে:

1. গুগল অ্যানালিটিক্স অ্যাডমিন পেজে যান।
2. প্রপার্টি কলামে, ডেটা সংগ্রহ এবং পরিবর্তন-এ ক্লিক করুন, তারপর ডেটা স্ট্রিমস নির্বাচন করুন।
3. অ্যাড স্ট্রিম-এ ক্লিক করুন, তারপর ওয়েব-এ ক্লিক করুন।
4. ওয়েবসাইট ইউআরএল ফিল্ডে যেকোনো একটি প্লেসহোল্ডার ইউআরএল দিন (যেমন, https://extension অথবা আপনার এক্সটেনশনের ক্রোম ওয়েব স্টোর ইউআরএল)।
5. একটি স্ট্রিমের নাম লিখুন (উদাহরণস্বরূপ, My Chrome Extension )।
6. স্ট্রিম তৈরি করুন -এ ক্লিক করুন।

একবার তৈরি হয়ে গেলে, আপনার মেজারমেন্ট আইডি (যা G-XXXXXXXXXX এর মতো দেখতে) স্ট্রিম ডিটেইলস পেজের শীর্ষে প্রদর্শিত হবে।

ধাপ ২: একটি মেজারমেন্ট প্রোটোকল এপিআই সিক্রেট তৈরি করুন

মেজারমেন্ট প্রোটোকলের জন্য প্রয়োজনীয় api_secret তৈরি করতে, আপনার এইমাত্র তৈরি করা ওয়েব ডেটা স্ট্রিমের সেটিংসে যান:

1. অ্যাডমিন > ডেটা সংগ্রহ ও পরিবর্তন > ডেটা স্ট্রিম- এ যান এবং আপনার ওয়েব ডেটা স্ট্রিমটি নির্বাচন করুন।

2. ইভেন্টস সেকশনে, মেজারমেন্ট প্রোটোকল এপিআই সিক্রেটস- এ ক্লিক করুন।

3. অনুরোধ করা হলে, পরিমাপ প্রোটোকলের শর্তাবলী পড়ুন এবং গ্রহণ করুন।

4. তৈরি করুন- এ ক্লিক করুন।

5. আপনার সিক্রেটের জন্য একটি ডাকনাম লিখুন (উদাহরণস্বরূপ, Chrome Extension Secret ) এবং সিক্রেটটি তৈরি করতে Create-এ ক্লিক করুন।

6. তৈরি হওয়া Secret মানটি কপি করুন।

একটি 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;
}

একটি অ্যানালিটিক্স ইভেন্ট পাঠান

API ক্রেডেনশিয়াল এবং client_id ব্যবহার করে, আপনি একটি fetch রিকোয়েস্টের মাধ্যমে গুগল অ্যানালিটিক্সে একটি ইভেন্ট পাঠাতে পারেন:

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 ইভেন্ট পাঠায় যা আপনার গুগল অ্যানালিটিক্স ইভেন্টস রিপোর্টে দেখা যাবে। আপনি যদি গুগল অ্যানালিটিক্স রিয়েলটাইম রিপোর্টে আপনার ইভেন্টগুলো দেখতে চান, তাহলে আপনাকে আরও দুটি প্যারামিটার দিতে হবে: session_id এবং engagement_time_msec ।

প্রস্তাবিত প্যারামিটার session_id এবং engagement_time_msec ব্যবহার করুন

গুগল অ্যানালিটিক্স মেজারমেন্ট প্রোটোকল ব্যবহার করার সময় session_id এবং engagement_time_msec উভয়ই প্রস্তাবিত প্যারামিটার, কারণ রিয়েলটাইমের মতো স্ট্যান্ডার্ড রিপোর্টে ব্যবহারকারীর কার্যকলাপ প্রদর্শনের জন্য এগুলি প্রয়োজন।

একটি session_id এমন একটি সময়কালকে বোঝায়, যে সময়ে একজন ব্যবহারকারী আপনার এক্সটেনশনটির সাথে ক্রমাগত মিথস্ক্রিয়া করেন। ডিফল্টরূপে, ব্যবহারকারী ৩০ মিনিট নিষ্ক্রিয় থাকলে একটি সেশন শেষ হয়ে যায়। একটি সেশন কতক্ষণ স্থায়ী হতে পারে তার কোনো সীমা নেই।

সাধারণ ওয়েবসাইটের মতো নয়, ক্রোম এক্সটেনশনে ইউজার সেশন সম্পর্কে কোনো সুস্পষ্ট ধারণা নেই। তাই, আপনার এক্সটেনশনে ইউজার সেশন বলতে কী বোঝায়, তা আপনাকে অবশ্যই সংজ্ঞায়িত করতে হবে। উদাহরণস্বরূপ, ব্যবহারকারীর প্রতিটি নতুন ইন্টারঅ্যাকশন একটি নতুন সেশন হতে পারে। সেক্ষেত্রে, আপনি টাইমস্ট্যাম্পের মতো কোনো কিছু ব্যবহার করে প্রতিটি ইভেন্টের সাথে একটি নতুন সেশন আইডি তৈরি করতে পারেন।

নিম্নলিখিত উদাহরণটি এমন একটি পদ্ধতি প্রদর্শন করে যা ৩০ মিনিট ধরে কোনো ইভেন্ট রিপোর্ট না হলে একটি নতুন সেশনকে টাইমআউট করে দেবে (এই সময়টি আপনার এক্সটেনশনের ব্যবহারকারীর আচরণের সাথে আরও ভালোভাবে মানিয়ে নেওয়ার জন্য কাস্টমাইজ করা যেতে পারে)। উদাহরণটি ব্রাউজার চলার সময় সক্রিয় সেশন সংরক্ষণ করতে 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",
          },
        },
      ],
    }),
  }
);

গুগল অ্যানালিটিক্স রিয়েলটাইম রিপোর্টে ইভেন্টটি নিম্নরূপভাবে প্রদর্শিত হবে।

পপআপ, সাইড প্যানেল এবং এক্সটেনশন পেজগুলিতে পেজ ভিউ ট্র্যাক করুন।

গুগল অ্যানালিটিক্স মেজারমেন্ট প্রোটোকল পেজ ভিউ ট্র্যাক করার জন্য একটি বিশেষ page_view ইভেন্ট সমর্থন করে। ব্যবহারকারীরা নতুন ট্যাবে আপনার ডায়ালগ বক্স, মেনু পেজ, সাইড প্যানেল এবং এক্সটেনশন পেজ ভিজিট করলে তা ট্র্যাক করতে এটি ব্যবহার করুন। page_view ইভেন্টের জন্য ' page_title এবং page_location প্যারামিটারও প্রয়োজন। নিচের উদাহরণটি একটি এক্সটেনশন মেনুর ডকুমেন্ট load ইভেন্টে একটি 'page_view' ইভেন্ট ফায়ার করে:

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
          },
        },
      ],
    }),
  });
});

আপনার পপআপের html ফাইলে 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>

গুগল অ্যানালিটিক্স রিয়েলটাইম রিপোর্টে পপআপ ভিউটি অন্য যেকোনো পেজ ভিউয়ের মতোই প্রদর্শিত হবে:

সার্ভিস ওয়ার্কারদের মধ্যে অ্যানালিটিক্স ইভেন্ট ট্র্যাক করুন

গুগল অ্যানালিটিক্স মেজারমেন্ট প্রোটোকল ব্যবহার করে এক্সটেনশন সার্ভিস ওয়ার্কারগুলিতে অ্যানালিটিক্স ইভেন্ট ট্র্যাক করা সম্ভব হয়। উদাহরণস্বরূপ, আপনার সার্ভিস ওয়ার্কারে unhandledrejection event লিসেন করার মাধ্যমে, আপনি আপনার সার্ভিস ওয়ার্কারের যেকোনো আনক্যাচড এক্সেপশন গুগল অ্যানালিটিক্সে লগ করতে পারেন, যা আপনার ব্যবহারকারীদের রিপোর্ট করা সমস্যাগুলো ডিবাগ করতে ব্যাপকভাবে সাহায্য করতে পারে।

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,
          },
        },
      ],
    }),
  });
});

আপনি এখন আপনার গুগল অ্যানালিটিক্স রিপোর্টে ত্রুটির ইভেন্টটি দেখতে পাবেন:

ডিবাগিং

গুগল অ্যানালিটিক্স আপনার এক্সটেনশনে অ্যানালিটিক্স ইভেন্ট ডিবাগ করার জন্য দুটি সহায়ক বৈশিষ্ট্য প্রদান করে:

1. একটি বিশেষ ডিবাগিং এন্ডপয়েন্ট https://www.google-analytics.com**/debug**/mp/collect , যা আপনার ইভেন্ট ডেফিনিশনের যেকোনো ত্রুটি রিপোর্ট করবে।
2. গুগল অ্যানালিটিক্স রিয়েলটাইম রিপোর্ট , যা ইভেন্টগুলো আসার সাথে সাথে প্রদর্শন করবে।