@wxt-dev/analytics 0.2.8 → 0.4.1

package/README.md

@@ -1,90 +1,269 @@
 # WXT Analytics
 
-Add analytics, like google analytics, to your WXT extension.
+Report analytics events from your web extension extension.
 
 ## Supported Analytics Providers
 
 - [Google Analytics 4 (Measurement Protocol)](#google-analytics-4-measurement-protocol)
 - [Umami](#umami)
 
-## Installation
+## Install With WXT
 
-Install the NPM package:
+1. Install the NPM package:
+   ```bash
+   pnpm i @wxt-dev/analytics
+   ```
+2. In your `wxt.config.ts`, add the WXT module:
+   ```ts
+   export default defineConfig({
+     modules: ['@wxt-dev/analytics/module'],
+   });
+   ```
+3. In your `<srcDir>/app.config.ts`, add a provider:
 
-```bash
-pnpm i @wxt-dev/analytics
-```
+   ```ts
+   // <srcDir>/app.config.ts
+   import { umami } from '@wxt-dev/analytics/providers/umami';
 
-Then add the module to your `wxt.config.ts` file:
+   export default defineAppConfig({
+     analytics: {
+       debug: true,
+       providers: [
+         // ...
+       ],
+     },
+   });
+   ```
 
-```ts
-export default defineConfig({
-  modules: ['@wxt-dev/analytics'],
-});
+4. Then use the `#analytics` module to report events:
+
+   ```ts
+   import { analytics } from '#analytics';
+
+   await analytics.track('some-event');
+   await analytics.page();
+   await analytics.identify('some-user-id');
+   analytics.autoTrack(document.body);
+   ```
+
+## Install Without WXT
+
+1. Install the NPM package:
+   ```bash
+   pnpm i @wxt-dev/analytics
+   ```
+2. Create an `analytics` instance:
+
+   ```ts
+   // utils/analytics.ts
+   import { createAnalytics } from '@wxt-dev/analytics';
+
+   export const analytics = createAnalytics({
+     providers: [
+       // ...
+     ],
+   });
+   ```
+
+3. Import your analytics module in the background to initialize the message listener:
+   ```ts
+   // background.ts
+   import './utils/analytics';
+   ```
+4. Then use your `analytics` instance to report events:
+
+   ```ts
+   import { analytics } from './utils/analytics';
+
+   await analytics.track('some-event');
+   await analytics.page();
+   await analytics.identify('some-user-id');
+   analytics.autoTrack(document.body);
+   ```
+
+## Providers
+
+### Google Analytics 4 (Measurement Protocol)
+
+The [Measurement Protocol](https://developers.google.com/analytics/devguides/collection/protocol/ga4) is an alternative to GTag for reporting events to Google Analytics for MV3 extensions.
+
+> [Why use the Measurement Protocol instead of GTag?](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#measurement-protocol)
+
+Follow [Google's documentation](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#setup-credentials) to obtain your credentials and put them in your `.env` file:
+
+```dotenv
+WXT_GA_API_SECRET='...'
 ```
 
-Create an `app.config.ts` file and fill out the required config:
+Then add the `googleAnalytics4` provider to your `<srcDir>/app.config.ts` file:
 
 ```ts
-// <srcDir>/app.config.ts
+import { googleAnalytics4 } from '@wxt-dev/analytics/providers/google-analytics-4';
+
 export default defineAppConfig({
   analytics: {
-    debug: true,
     providers: [
-      // ...
+      googleAnalytics4({
+        apiSecret: import.meta.env.WXT_GA_API_SECRET,
+        measurementId: '...',
+      }),
     ],
   },
 });
 ```
 
-Then use the `analytics` import to report events:
+### Umami
 
-```ts
-import { analytics } from '#analytics';
+[Umami](https://umami.is/) is a privacy-first, open source analytics platform.
 
-await analytics.track('some-event');
-await analytics.page();
-await analytics.identify('some-user-id');
-analytics.autoTrack(document.body);
-```
+In Umami's dashboard, create a new website. The website's name and domain can be anything. Obviously, an extension doesn't have a domain, so make one up if you don't have one.
 
-## Providers
+After the website has been created, save the website ID and domain to your `.env` file:
 
-### Google Analytics 4 (Measurement Protocol)
+```dotenv
+WXT_UMAMI_WEBSITE_ID='...'
+WXT_UMAMI_DOMAIN='...'
+```
 
-Follow [Google's documentation](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#setup-credentials) to obtain your credentials:
+Then add the `umami` provider to your `<srcDir>/app.config.ts` file:
 
 ```ts
-import { googleAnalytics4 } from '@wxt-dev/analytics/providers/google-analytics-4';
+import { umami } from '@wxt-dev/analytics/providers/umami';
 
 export default defineAppConfig({
   analytics: {
     providers: [
-      googleAnalytics4({
-        apiSecret: '...',
-        measurementId: '...',
+      umami({
+        apiUrl: 'https://<your-umami-instance>/api',
+        websiteId: import.meta.env.WXT_UMAMI_WEBSITE_ID,
+        domain: import.meta.env.WXT_UMAMI_DOMAIN,
       }),
     ],
   },
 });
 ```
 
-> [Why use the Measurement Protocol instead of GTag?](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#measurement-protocol)
+### Custom Provider
 
-### Umami
+If your analytics platform is not supported, you can provide an implementation of the `AnalyticsProvider` type in your `app.config.ts` instead:
 
 ```ts
-import { umami } from '@wxt-dev/analytics/providers/umami';
+import { defineAnalyticsProvider } from '@wxt-dev/analytics/client';
+
+interface CustomAnalyticsOptions {
+  // ...
+}
+
+const customAnalytics = defineAnalyticsProvider<CustomAnalyticsOptions>(
+  (analytics, analyticsConfig, providerOptions) => {
+    // ...
+  },
+);
 
 export default defineAppConfig({
   analytics: {
     providers: [
-      umami({
-        baseUrl: 'https://your-domain.com',
-        websiteId: '...',
-        hostname: '...',
+      customAnalytics({
+        // ...
       }),
     ],
   },
 });
 ```
+
+Example `AnalyticsProvider` implementations can be found at [`./modules/analytics/providers`](https://github.com/wxt-dev/wxt/tree/main/packages/analytics/modules/analytics/providers).
+
+## User Properties
+
+User ID and properties are stored in `browser.storage.local`. To change this or customize where these values are stored, use the `userId` and `userProperties` config:
+
+```ts
+// app.config.ts
+import { storage } from 'wxt/storage';
+
+export default defineAppConfig({
+  analytics: {
+    userId: storage.defineItem('local:custom-user-id-key'),
+    userProperties: storage.defineItem('local:custom-user-properties-key'),
+  },
+});
+```
+
+To set the values at runtime, use the `identify` function:
+
+```ts
+await analytics.identify(userId, userProperties);
+```
+
+Alternatively, a common pattern is to use a random string as the user ID. This keeps the actual user information private, while still providing useful metrics in your analytics platform. This can be done very easily using WXT's storage API:
+
+```ts
+// app.config.ts
+import { storage } from 'wxt/storage';
+
+export default defineAppConfig({
+  analytics: {
+    userId: storage.defineItem('local:custom-user-id-key', {
+      init: () => crypto.randomUUID(),
+    }),
+  },
+});
+```
+
+If you aren't using `wxt` or `@wxt-dev/storage`, you can define custom implementations for the `userId` and `userProperties` config:
+
+```ts
+const analytics = createAnalytics({
+  userId: {
+    getValue: () => ...,
+    setValue: (userId) => ...,
+  }
+})
+```
+
+## Auto-track UI events
+
+Call `analytics.autoTrack(container)` to automatically track UI events so you don't have to manually add them. Currently it:
+
+- Tracks clicks to elements inside the `container`
+
+In your extension's HTML pages, you'll want to call it with `document`:
+
+```ts
+analytics.autoTrack(document);
+```
+
+But in content scripts, you usually only care about interactions with your own UI:
+
+```ts
+const ui = createIntegratedUi({
+  // ...
+  onMount(container) {
+    analytics.autoTrack(container);
+  },
+});
+ui.mount();
+```
+
+## Enabling/Disabling
+
+By default, **analytics is disabled**. You can configure how the value is stored (and change the default value) via the `enabled` config:
+
+```ts
+// app.config.ts
+import { storage } from 'wxt/storage';
+
+export default defineAppConfig({
+  analytics: {
+    enabled: storage.defineItem('local:analytics-enabled', {
+      fallback: true,
+    }),
+  },
+});
+```
+
+At runtime, you can call `setEnabled` to change the value:
+
+```ts
+analytics.setEnabled(true);
+```

package/dist/background-plugin.d.mts

@@ -0,0 +1,3 @@
+declare const _default: () => void;
+
+export { _default as default };

package/dist/background-plugin.d.ts

@@ -0,0 +1,3 @@
+declare const _default: () => void;
+
+export { _default as default };

package/dist/background-plugin.mjs

@@ -0,0 +1,6 @@
+import '#analytics';
+
+const backgroundPlugin = () => {
+};
+
+export { backgroundPlugin as default };

package/dist/index.d.mts

@@ -1,11 +1,12 @@
-import * as wxt from 'wxt';
-import { A as AnalyticsConfig } from './shared/analytics.2893a879.mjs';
+import { AnalyticsConfig, Analytics, AnalyticsProvider } from './types.mjs';
 
-declare module 'wxt/sandbox' {
-    interface WxtAppConfig {
-        analytics: AnalyticsConfig;
-    }
-}
-declare const _default: wxt.WxtModule<wxt.WxtModuleOptions>;
+declare function createAnalytics(config?: AnalyticsConfig): Analytics;
+declare function defineAnalyticsProvider<T = never>(definition: (
+/** The analytics object. */
+analytics: Analytics, 
+/** Config passed into the analytics module from `app.config.ts`. */
+config: AnalyticsConfig, 
+/** Provider options */
+options: T) => ReturnType<AnalyticsProvider>): (options: T) => AnalyticsProvider;
 
-export { _default as default };
+export { createAnalytics, defineAnalyticsProvider };

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import * as wxt from 'wxt';
-import { A as AnalyticsConfig } from './shared/analytics.2893a879.js';
+import { AnalyticsConfig, Analytics, AnalyticsProvider } from './types.js';
 
-declare module 'wxt/sandbox' {
-    interface WxtAppConfig {
-        analytics: AnalyticsConfig;
-    }
-}
-declare const _default: wxt.WxtModule<wxt.WxtModuleOptions>;
+declare function createAnalytics(config?: AnalyticsConfig): Analytics;
+declare function defineAnalyticsProvider<T = never>(definition: (
+/** The analytics object. */
+analytics: Analytics, 
+/** Config passed into the analytics module from `app.config.ts`. */
+config: AnalyticsConfig, 
+/** Provider options */
+options: T) => ReturnType<AnalyticsProvider>): (options: T) => AnalyticsProvider;
 
-export { _default as default };
+export { createAnalytics, defineAnalyticsProvider };

package/dist/index.mjs

@@ -1,36 +1,208 @@
-import 'wxt';
-import 'wxt/sandbox';
-import { defineWxtModule, addAlias } from 'wxt/modules';
-import { resolve } from 'node:path';
+import { UAParser } from 'ua-parser-js';
 
-const index = defineWxtModule({
-  name: "analytics",
-  imports: [{ name: "analytics", from: "#analytics" }],
-  setup(wxt) {
-    wxt.hook("build:manifestGenerated", (_, manifest) => {
-      manifest.permissions ?? (manifest.permissions = []);
-      if (!manifest.permissions.includes("storage")) {
-        manifest.permissions.push("storage");
-      }
-    });
-    const analyticsModulePath = resolve(
-      wxt.config.wxtDir,
-      "analytics/index.ts"
+const ANALYTICS_PORT = "@wxt-dev/analytics";
+function createAnalytics(config) {
+  if (typeof chrome === "undefined" || !chrome?.runtime?.id)
+    throw Error(
+      "Cannot use WXT analytics in contexts without access to the browser.runtime APIs"
+    );
+  if (config == null) {
+    console.warn(
+      "[@wxt-dev/analytics] Config not provided to createAnalytics. If you're using WXT, add the 'analytics' property to '<srcDir>/app.config.ts'."
     );
-    const analyticsModuleCode = `
-import { createAnalytics } from '@wxt-dev/analytics/client';
-import { useAppConfig } from 'wxt/client';
-
-export const analytics = createAnalytics(useAppConfig().analytics);
-    `;
-    addAlias(wxt, "#analytics", analyticsModulePath);
-    wxt.hook("prepare:types", async (_, entries) => {
-      entries.push({
-        path: analyticsModulePath,
-        text: analyticsModuleCode
-      });
-    });
   }
-});
+  if (location.pathname === "/background.js")
+    return createBackgroundAnalytics(config);
+  return createFrontendAnalytics();
+}
+function createBackgroundAnalytics(config) {
+  const userIdStorage = config?.userId ?? defineStorageItem("wxt-analytics:user-id");
+  const userPropertiesStorage = config?.userProperties ?? defineStorageItem(
+    "wxt-analytics:user-properties",
+    {}
+  );
+  const enabled = config?.enabled ?? defineStorageItem("local:wxt-analytics:enabled", false);
+  const platformInfo = chrome.runtime.getPlatformInfo();
+  const userAgent = UAParser();
+  let userId = Promise.resolve(userIdStorage.getValue()).then(
+    (id) => id ?? globalThis.crypto.randomUUID()
+  );
+  let userProperties = userPropertiesStorage.getValue();
+  const manifest = chrome.runtime.getManifest();
+  const getBackgroundMeta = () => ({
+    timestamp: Date.now(),
+    // Don't track sessions for the background, it can be running
+    // indefinitely, and will inflate session duration stats.
+    sessionId: void 0,
+    language: navigator.language,
+    referrer: void 0,
+    screen: void 0,
+    url: location.href,
+    title: void 0
+  });
+  const getBaseEvent = async (meta) => {
+    const platform = await platformInfo;
+    return {
+      meta,
+      user: {
+        id: await userId,
+        properties: {
+          version: config?.version ?? manifest.version_name ?? manifest.version,
+          wxtMode: import.meta.env.MODE,
+          wxtBrowser: import.meta.env.BROWSER,
+          arch: platform.arch,
+          os: platform.os,
+          browser: userAgent.browser.name,
+          browserVersion: userAgent.browser.version,
+          ...await userProperties
+        }
+      }
+    };
+  };
+  const analytics = {
+    identify: async (newUserId, newUserProperties = {}, meta = getBackgroundMeta()) => {
+      userId = Promise.resolve(newUserId);
+      userProperties = Promise.resolve(newUserProperties);
+      await Promise.all([
+        userIdStorage.setValue?.(newUserId),
+        userPropertiesStorage.setValue?.(newUserProperties)
+      ]);
+      const event = await getBaseEvent(meta);
+      if (config?.debug)
+        console.debug("[@wxt-dev/analytics] identify", event);
+      if (await enabled.getValue()) {
+        await Promise.allSettled(
+          providers.map((provider) => provider.identify(event))
+        );
+      } else if (config?.debug) {
+        console.debug(
+          "[@wxt-dev/analytics] Analytics disabled, identify() not uploaded"
+        );
+      }
+    },
+    page: async (location2, meta = getBackgroundMeta()) => {
+      const baseEvent = await getBaseEvent(meta);
+      const event = {
+        ...baseEvent,
+        page: {
+          url: meta?.url ?? globalThis.location?.href,
+          location: location2,
+          title: meta?.title ?? globalThis.document?.title
+        }
+      };
+      if (config?.debug)
+        console.debug("[@wxt-dev/analytics] page", event);
+      if (await enabled.getValue()) {
+        await Promise.allSettled(
+          providers.map((provider) => provider.page(event))
+        );
+      } else if (config?.debug) {
+        console.debug(
+          "[@wxt-dev/analytics] Analytics disabled, page() not uploaded"
+        );
+      }
+    },
+    track: async (eventName, eventProperties, meta = getBackgroundMeta()) => {
+      const baseEvent = await getBaseEvent(meta);
+      const event = {
+        ...baseEvent,
+        event: { name: eventName, properties: eventProperties }
+      };
+      if (config?.debug)
+        console.debug("[@wxt-dev/analytics] track", event);
+      if (await enabled.getValue()) {
+        await Promise.allSettled(
+          providers.map((provider) => provider.track(event))
+        );
+      } else if (config?.debug) {
+        console.debug(
+          "[@wxt-dev/analytics] Analytics disabled, track() not uploaded"
+        );
+      }
+    },
+    setEnabled: async (newEnabled) => {
+      await enabled.setValue?.(newEnabled);
+    },
+    autoTrack: () => {
+      return () => {
+      };
+    }
+  };
+  const providers = config?.providers?.map((provider) => provider(analytics, config)) ?? [];
+  chrome.runtime.onConnect.addListener((port) => {
+    if (port.name === ANALYTICS_PORT) {
+      port.onMessage.addListener(({ fn, args }) => {
+        void analytics[fn]?.(...args);
+      });
+    }
+  });
+  return analytics;
+}
+function createFrontendAnalytics() {
+  const port = chrome.runtime.connect({ name: ANALYTICS_PORT });
+  const sessionId = Date.now();
+  const getFrontendMetadata = () => ({
+    sessionId,
+    timestamp: Date.now(),
+    language: navigator.language,
+    referrer: globalThis.document?.referrer || void 0,
+    screen: globalThis.window ? `${globalThis.window.screen.width}x${globalThis.window.screen.height}` : void 0,
+    url: location.href,
+    title: document.title || void 0
+  });
+  const methodForwarder = (fn) => (...args) => {
+    port.postMessage({ fn, args: [...args, getFrontendMetadata()] });
+  };
+  const analytics = {
+    identify: methodForwarder("identify"),
+    page: methodForwarder("page"),
+    track: methodForwarder("track"),
+    setEnabled: methodForwarder("setEnabled"),
+    autoTrack: (root) => {
+      const onClick = (event) => {
+        const element = event.target;
+        if (!element || !INTERACTIVE_TAGS.has(element.tagName) && !INTERACTIVE_ROLES.has(element.getAttribute("role")))
+          return;
+        void analytics.track("click", {
+          tagName: element.tagName?.toLowerCase(),
+          id: element.id || void 0,
+          className: element.className || void 0,
+          textContent: element.textContent?.substring(0, 50) || void 0,
+          // Limit text content length
+          href: element.href
+        });
+      };
+      root.addEventListener("click", onClick, { capture: true, passive: true });
+      return () => {
+        root.removeEventListener("click", onClick);
+      };
+    }
+  };
+  return analytics;
+}
+function defineStorageItem(key, defaultValue) {
+  return {
+    getValue: async () => (await chrome.storage.local.get(key))[key] ?? defaultValue,
+    setValue: (newValue) => chrome.storage.local.set({ [key]: newValue })
+  };
+}
+const INTERACTIVE_TAGS = /* @__PURE__ */ new Set([
+  "A",
+  "BUTTON",
+  "INPUT",
+  "SELECT",
+  "TEXTAREA"
+]);
+const INTERACTIVE_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "checkbox",
+  "menuitem",
+  "tab",
+  "radio"
+]);
+function defineAnalyticsProvider(definition) {
+  return (options) => (analytics, config) => definition(analytics, config, options);
+}
 
-export { index as default };
+export { createAnalytics, defineAnalyticsProvider };

package/dist/module.d.mts

@@ -0,0 +1,11 @@
+import * as wxt from 'wxt';
+import { AnalyticsConfig } from './types.mjs';
+
+declare module 'wxt/sandbox' {
+    interface WxtAppConfig {
+        analytics: AnalyticsConfig;
+    }
+}
+declare const _default: wxt.WxtModule<wxt.WxtModuleOptions>;
+
+export { _default as default };

package/dist/module.d.ts

@@ -0,0 +1,11 @@
+import * as wxt from 'wxt';
+import { AnalyticsConfig } from './types.js';
+
+declare module 'wxt/sandbox' {
+    interface WxtAppConfig {
+        analytics: AnalyticsConfig;
+    }
+}
+declare const _default: wxt.WxtModule<wxt.WxtModuleOptions>;
+
+export { _default as default };