update legacy ua analytics to ga4

Author: 0xdevalias

js/googleAnalytics.js

@@ -12,7 +12,8 @@
     "128": "icons/NewWindowWithTabsToRight-Icon@128px.png"
   },
   "permissions": [
-    "contextMenus"
+    "contextMenus",
+    "storage"
   ],
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'self'"

manifest.json

@@ -0,0 +1,127 @@
+// See:
+//   https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4
+//   https://developers.google.com/analytics/devguides/collection/protocol/ga4
+//   https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag
+//   https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/tutorial.google-analytics
+//   https://github.com/GoogleChrome/chrome-extensions-samples/blob/main/functional-samples/tutorial.google-analytics/scripts/google-analytics.js
+//   https://github.com/GoogleChrome/chrome-extensions-samples/blob/main/functional-samples/tutorial.google-analytics/service-worker.js
+
+const GA_ENDPOINT = 'https://www.google-analytics.com/mp/collect';
+const GA_DEBUG_ENDPOINT = 'https://www.google-analytics.com/debug/mp/collect';
+
+// Get via https://analytics.google.com/analytics/web/
+const MEASUREMENT_ID = 'G-BCGJGLETYW';
+const API_SECRET = '_xmXa00ATSmnNWs2J2xadQ';
+const DEFAULT_ENGAGEMENT_TIME_MSEC = 100;
+
+// Duration of inactivity after which a new session is created
+const SESSION_EXPIRATION_IN_MIN = 30;
+
+class Analytics {
+  constructor(debug = false) {
+    this.debug = debug;
+  }
+
+  // Returns the client id, or creates a new one if one doesn't exist.
+  // Stores client id in local storage to keep the same client id as long as
+  // the extension is installed.
+  async getOrCreateClientId() {
+    let { clientId } = await chrome.storage.local.get('clientId');
+    if (!clientId) {
+      // Generate a unique client ID, the actual value is not relevant
+      clientId = self.crypto.randomUUID();
+      await chrome.storage.local.set({ clientId });
+    }
+    return clientId;
+  }
+
+  // Returns the current session id, or creates a new one if one doesn't exist or
+  // the previous one has expired.
+  async getOrCreateSessionId() {
+    // Use storage.session because it is only in memory
+    let { sessionData } = await chrome.storage.session.get('sessionData');
+    const currentTimeInMs = Date.now();
+    // Check if session exists and is still valid
+    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) {
+        // Clear 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;
+  }
+
+  // Fires an event with optional params. Event names must only include letters and underscores.
+  async fireEvent(name, params = {}) {
+    // Configure session id and engagement time if not present, for more details see:
+    // https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag#recommended_parameters_for_reports
+    if (!params.session_id) {
+      params.session_id = await this.getOrCreateSessionId();
+    }
+    if (!params.engagement_time_msec) {
+      params.engagement_time_msec = DEFAULT_ENGAGEMENT_TIME_MSEC;
+    }
+
+    try {
+      const response = await fetch(
+        `${
+          this.debug ? GA_DEBUG_ENDPOINT : GA_ENDPOINT
+        }?measurement_id=${MEASUREMENT_ID}&api_secret=${API_SECRET}`,
+        {
+          method: 'POST',
+          body: JSON.stringify({
+            client_id: await this.getOrCreateClientId(),
+            events: [
+              {
+                name,
+                params
+              }
+            ]
+          })
+        }
+      );
+      if (!this.debug) {
+        return;
+      }
+      console.log(await response.text());
+    } catch (e) {
+      console.error('Google Analytics request failed with an exception', e);
+    }
+  }
+
+  // Fire a page view event.
+  async firePageViewEvent(pageTitle, pageLocation, additionalParams = {}) {
+    return this.fireEvent('page_view', {
+      page_title: pageTitle,
+      page_location: pageLocation,
+      ...additionalParams
+    });
+  }
+
+  // Fire an error event.
+  async fireErrorEvent(error, additionalParams = {}) {
+    // 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
+    return this.fireEvent('extension_error', {
+      ...error,
+      ...additionalParams
+    });
+  }
+}
+
+export default new Analytics();

src/google-analytics.js

@@ -1,3 +1,5 @@
+import Analytics from './google-analytics.js';
+
 /**
  * Handles the extension's installation event.
  * Sets up context menus.
@@ -6,7 +8,7 @@
  * @see {@link https://developer.chrome.com/docs/extensions/reference/api/contextMenus#method-create}
  * @see {@link https://developer.chrome.com/docs/extensions/develop/ui/context-menu}
  */
-chrome.runtime.onInstalled.addListener(() => {
+chrome.runtime.onInstalled.addListener(async (details) => {
   const menuContexts = ["page"];
 
   const menuRoot = chrome.contextMenus.create({
@@ -42,6 +44,10 @@ chrome.runtime.onInstalled.addListener(() => {
     id: aboutTheDeveloper.name,
     title: "About the Developer"
   });
+
+  await Analytics.fireEvent('extension_lifecycle', {
+    reason: details.reason
+  });
 });
 
 /**
@@ -60,6 +66,11 @@ chrome.contextMenus.onClicked.addListener(async (info, tab) => {
   };
 
   await handlers[info.menuItemId]?.(tab);
+
+  await Analytics.fireEvent('task_triggered', {
+    source: 'contextMenu',
+    task: info.menuItemId
+  });
 });
 
 /**
@@ -77,6 +88,11 @@ chrome.commands.onCommand.addListener(async (command, tab) => {
   };
 
   await handlers[command]?.(tab);
+
+  await Analytics.fireEvent('task_triggered', {
+    source: 'command',
+    task: command
+  });
 });
 
 /**