@wxt-dev/analytics 0.4.0 → 0.5.0

package/README.md

@@ -172,3 +172,98 @@ export default defineAppConfig({
 ```
 
 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/index.mjs

@@ -68,8 +68,7 @@ function createBackgroundAnalytics(config) {
         userPropertiesStorage.setValue?.(newUserProperties)
       ]);
       const event = await getBaseEvent(meta);
-      if (config?.debug)
-        console.debug("[@wxt-dev/analytics] identify", event);
+      if (config?.debug) console.debug("[@wxt-dev/analytics] identify", event);
       if (await enabled.getValue()) {
         await Promise.allSettled(
           providers.map((provider) => provider.identify(event))
@@ -90,8 +89,7 @@ function createBackgroundAnalytics(config) {
           title: meta?.title ?? globalThis.document?.title
         }
       };
-      if (config?.debug)
-        console.debug("[@wxt-dev/analytics] page", event);
+      if (config?.debug) console.debug("[@wxt-dev/analytics] page", event);
       if (await enabled.getValue()) {
         await Promise.allSettled(
           providers.map((provider) => provider.page(event))
@@ -108,8 +106,7 @@ function createBackgroundAnalytics(config) {
         ...baseEvent,
         event: { name: eventName, properties: eventProperties }
       };
-      if (config?.debug)
-        console.debug("[@wxt-dev/analytics] track", event);
+      if (config?.debug) console.debug("[@wxt-dev/analytics] track", event);
       if (await enabled.getValue()) {
         await Promise.allSettled(
           providers.map((provider) => provider.track(event))

package/dist/module.d.mts

@@ -1,7 +1,7 @@
 import * as wxt from 'wxt';
 import { AnalyticsConfig } from './types.mjs';
 
-declare module 'wxt/sandbox' {
+declare module 'wxt/utils/define-app-config' {
     interface WxtAppConfig {
         analytics: AnalyticsConfig;
     }

package/dist/module.d.ts

@@ -1,7 +1,7 @@
 import * as wxt from 'wxt';
 import { AnalyticsConfig } from './types.js';
 
-declare module 'wxt/sandbox' {
+declare module 'wxt/utils/define-app-config' {
     interface WxtAppConfig {
         analytics: AnalyticsConfig;
     }

package/dist/module.mjs

@@ -1,6 +1,6 @@
 import 'wxt';
-import 'wxt/sandbox';
-import { defineWxtModule, addAlias, addWxtPlugin } from 'wxt/modules';
+import 'wxt/utils/define-app-config';
+import { defineWxtModule, addAlias, addWxtPlugin, addViteConfig } from 'wxt/modules';
 import { resolve } from 'node:path';
 
 const index = defineWxtModule({
@@ -12,14 +12,14 @@ const index = defineWxtModule({
     const clientModuleId = "@wxt-dev/analytics" ;
     const pluginModuleId = "@wxt-dev/analytics/background-plugin" ;
     wxt.hook("build:manifestGenerated", (_, manifest) => {
-      manifest.permissions ?? (manifest.permissions = []);
+      manifest.permissions ??= [];
       if (!manifest.permissions.includes("storage")) {
         manifest.permissions.push("storage");
       }
     });
     const wxtAnalyticsCode = [
       `import { createAnalytics } from '${clientModuleId }';`,
-      `import { useAppConfig } from 'wxt/client';`,
+      `import { useAppConfig } from '#imports';`,
       ``,
       `export const analytics = createAnalytics(useAppConfig().analytics);`,
       ``
@@ -47,6 +47,14 @@ const index = defineWxtModule({
       }
     });
     addWxtPlugin(wxt, pluginModuleId);
+    addViteConfig(wxt, () => ({
+      optimizeDeps: {
+        // Ensure the "#analytics" import is processed by vite in the background plugin
+        exclude: ["@wxt-dev/analytics"],
+        // Ensure the CJS subdependency is preprocessed into ESM
+        include: ["@wxt-dev/analytics > ua-parser-js"]
+      }
+    }));
   }
 });
 

package/dist/types.d.mts

@@ -1,13 +1,13 @@
 interface Analytics {
-    /** Report a page change */
+    /** Report a page change. */
     page: (url: string) => void;
-    /** Report a custom event */
+    /** Report a custom event. */
     track: (eventName: string, eventProperties?: Record<string, string>) => void;
-    /** Save information about the user */
+    /** Save information about the user. */
     identify: (userId: string, userProperties?: Record<string, string>) => void;
     /** Automatically setup and track user interactions, returning a function to remove any listeners that were setup. */
     autoTrack: (root: Document | ShadowRoot | Element) => () => void;
-    /** Calls `config.enabled.setValue` */
+    /** Calls `config.enabled.setValue`. */
     setEnabled: (enabled: boolean) => void;
 }
 interface AnalyticsConfig {
@@ -20,19 +20,20 @@ interface AnalyticsConfig {
      */
     debug?: boolean;
     /**
-     * Extension version, defaults to `browser.runtime.getManifest().version`.
+     * Your extension's version, reported alongside events.
+     * @default browser.runtime.getManifest().version`.
      */
     version?: string;
     /**
-     * Configure how the enabled flag is persisted. Defaults to using `""` in local extension storage.
+     * Configure how the enabled flag is persisted. Defaults to using `browser.storage.local`.
      */
     enabled?: AnalyticsStorageItem<boolean>;
     /**
-     * Configure how the user Id is persisted
+     * Configure how the user Id is persisted. Defaults to using `browser.storage.local`.
      */
     userId?: AnalyticsStorageItem<string>;
     /**
-     * Configure how user properties are persisted
+     * Configure how user properties are persisted. Defaults to using `browser.storage.local`.
      */
     userProperties?: AnalyticsStorageItem<Record<string, string>>;
 }
@@ -41,11 +42,11 @@ interface AnalyticsStorageItem<T> {
     setValue?: (newValue: T) => void | Promise<void>;
 }
 type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
-    /** Upload a page view event */
+    /** Upload a page view event. */
     page: (event: AnalyticsPageViewEvent) => Promise<void>;
-    /** Upload a custom event */
+    /** Upload a custom event. */
     track: (event: AnalyticsTrackEvent) => Promise<void>;
-    /** Upload information about the user */
+    /** Upload information about the user. */
     identify: (event: BaseAnalyticsEvent) => Promise<void>;
 };
 interface BaseAnalyticsEvent {
@@ -56,11 +57,11 @@ interface BaseAnalyticsEvent {
     };
 }
 interface AnalyticsEventMetadata {
-    /** Identifier of the session the event was fired from */
+    /** Identifier of the session the event was fired from. */
     sessionId: number | undefined;
-    /** `Date.now()` of when the event was reported */
+    /** `Date.now()` of when the event was reported. */
     timestamp: number;
-    /** `"1920x1080"` */
+    /** Ex: `"1920x1080"`. */
     screen: string | undefined;
     /** `document.referrer` */
     referrer: string | undefined;

package/dist/types.d.ts

@@ -1,13 +1,13 @@
 interface Analytics {
-    /** Report a page change */
+    /** Report a page change. */
     page: (url: string) => void;
-    /** Report a custom event */
+    /** Report a custom event. */
     track: (eventName: string, eventProperties?: Record<string, string>) => void;
-    /** Save information about the user */
+    /** Save information about the user. */
     identify: (userId: string, userProperties?: Record<string, string>) => void;
     /** Automatically setup and track user interactions, returning a function to remove any listeners that were setup. */
     autoTrack: (root: Document | ShadowRoot | Element) => () => void;
-    /** Calls `config.enabled.setValue` */
+    /** Calls `config.enabled.setValue`. */
     setEnabled: (enabled: boolean) => void;
 }
 interface AnalyticsConfig {
@@ -20,19 +20,20 @@ interface AnalyticsConfig {
      */
     debug?: boolean;
     /**
-     * Extension version, defaults to `browser.runtime.getManifest().version`.
+     * Your extension's version, reported alongside events.
+     * @default browser.runtime.getManifest().version`.
      */
     version?: string;
     /**
-     * Configure how the enabled flag is persisted. Defaults to using `""` in local extension storage.
+     * Configure how the enabled flag is persisted. Defaults to using `browser.storage.local`.
      */
     enabled?: AnalyticsStorageItem<boolean>;
     /**
-     * Configure how the user Id is persisted
+     * Configure how the user Id is persisted. Defaults to using `browser.storage.local`.
      */
     userId?: AnalyticsStorageItem<string>;
     /**
-     * Configure how user properties are persisted
+     * Configure how user properties are persisted. Defaults to using `browser.storage.local`.
      */
     userProperties?: AnalyticsStorageItem<Record<string, string>>;
 }
@@ -41,11 +42,11 @@ interface AnalyticsStorageItem<T> {
     setValue?: (newValue: T) => void | Promise<void>;
 }
 type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
-    /** Upload a page view event */
+    /** Upload a page view event. */
     page: (event: AnalyticsPageViewEvent) => Promise<void>;
-    /** Upload a custom event */
+    /** Upload a custom event. */
     track: (event: AnalyticsTrackEvent) => Promise<void>;
-    /** Upload information about the user */
+    /** Upload information about the user. */
     identify: (event: BaseAnalyticsEvent) => Promise<void>;
 };
 interface BaseAnalyticsEvent {
@@ -56,11 +57,11 @@ interface BaseAnalyticsEvent {
     };
 }
 interface AnalyticsEventMetadata {
-    /** Identifier of the session the event was fired from */
+    /** Identifier of the session the event was fired from. */
     sessionId: number | undefined;
-    /** `Date.now()` of when the event was reported */
+    /** `Date.now()` of when the event was reported. */
     timestamp: number;
-    /** `"1920x1080"` */
+    /** Ex: `"1920x1080"`. */
     screen: string | undefined;
     /** `document.referrer` */
     referrer: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxt-dev/analytics",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Add analytics to your web extension",
   "repository": {
     "type": "git",
@@ -40,19 +40,19 @@
     "dist"
   ],
   "peerDependencies": {
-    "wxt": ">=0.19.23"
+    "wxt": ">=0.20.0"
   },
   "devDependencies": {
     "@aklinker1/check": "^1.4.5",
-    "@types/chrome": "^0.0.268",
+    "@types/chrome": "^0.0.280",
     "@types/ua-parser-js": "^0.7.39",
     "publint": "^0.2.12",
     "typescript": "^5.6.3",
-    "unbuild": "^2.0.0",
-    "wxt": "0.19.23"
+    "unbuild": "^3.5.0",
+    "wxt": "0.20.0"
   },
   "dependencies": {
-    "ua-parser-js": "^1.0.38"
+    "ua-parser-js": "^1.0.40"
   },
   "scripts": {
     "dev": "buildc --deps-only -- wxt",