@wxt-dev/analytics 0.2.7 → 0.4.0

package/README.md

@@ -1,89 +1,174 @@
 # 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
+
+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:
+
+   ```ts
+   // <srcDir>/app.config.ts
+   import { umami } from '@wxt-dev/analytics/providers/umami';
+
+   export default defineAppConfig({
+     analytics: {
+       debug: true,
+       providers: [
+         // ...
+       ],
+     },
+   });
+   ```
+
+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);
+   ```
 
-Install the NPM package:
+## Providers
 
-```bash
-pnpm i @wxt-dev/analytics
-```
+### Google Analytics 4 (Measurement Protocol)
 
-Then add the module to your `wxt.config.ts` file:
+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.
 
-```ts
-export default defineConfig({
-  modules: ['@wxt-dev/analytics'],
-});
+> [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 '@wxt-dev/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');
-```
+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).

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 };

package/dist/module.mjs

@@ -0,0 +1,53 @@
+import 'wxt';
+import 'wxt/sandbox';
+import { defineWxtModule, addAlias, addWxtPlugin } from 'wxt/modules';
+import { resolve } from 'node:path';
+
+const index = defineWxtModule({
+  name: "analytics",
+  imports: [{ name: "analytics", from: "#analytics" }],
+  setup(wxt) {
+    const wxtAnalyticsFolder = resolve(wxt.config.wxtDir, "analytics");
+    const wxtAnalyticsIndex = resolve(wxtAnalyticsFolder, "index.ts");
+    const clientModuleId = "@wxt-dev/analytics" ;
+    const pluginModuleId = "@wxt-dev/analytics/background-plugin" ;
+    wxt.hook("build:manifestGenerated", (_, manifest) => {
+      manifest.permissions ?? (manifest.permissions = []);
+      if (!manifest.permissions.includes("storage")) {
+        manifest.permissions.push("storage");
+      }
+    });
+    const wxtAnalyticsCode = [
+      `import { createAnalytics } from '${clientModuleId }';`,
+      `import { useAppConfig } from 'wxt/client';`,
+      ``,
+      `export const analytics = createAnalytics(useAppConfig().analytics);`,
+      ``
+    ].join("\n");
+    addAlias(wxt, "#analytics", wxtAnalyticsIndex);
+    wxt.hook("prepare:types", async (_, entries) => {
+      entries.push({
+        path: wxtAnalyticsIndex,
+        text: wxtAnalyticsCode
+      });
+    });
+    wxt.hook("entrypoints:resolved", (_, entrypoints) => {
+      const hasBackground = entrypoints.find(
+        (entry) => entry.type === "background"
+      );
+      if (!hasBackground) {
+        entrypoints.push({
+          type: "background",
+          inputPath: "virtual:user-background",
+          name: "background",
+          options: {},
+          outputDir: wxt.config.outDir,
+          skipped: false
+        });
+      }
+    });
+    addWxtPlugin(wxt, pluginModuleId);
+  }
+});
+
+export { index as default };

package/dist/providers/google-analytics-4.d.mts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.mjs';
+import { AnalyticsProvider } from '../types.mjs';
 
-interface GoogleAnalyticsProviderOptions {
+interface GoogleAnalytics4ProviderOptions {
     apiSecret: string;
     measurementId: string;
 }
-declare const googleAnalytics4: (options: GoogleAnalyticsProviderOptions) => AnalyticsProvider;
+declare const googleAnalytics4: (options: GoogleAnalytics4ProviderOptions) => AnalyticsProvider;
 
-export { type GoogleAnalyticsProviderOptions, googleAnalytics4 };
+export { type GoogleAnalytics4ProviderOptions, googleAnalytics4 };

package/dist/providers/google-analytics-4.d.ts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.js';
+import { AnalyticsProvider } from '../types.js';
 
-interface GoogleAnalyticsProviderOptions {
+interface GoogleAnalytics4ProviderOptions {
     apiSecret: string;
     measurementId: string;
 }
-declare const googleAnalytics4: (options: GoogleAnalyticsProviderOptions) => AnalyticsProvider;
+declare const googleAnalytics4: (options: GoogleAnalytics4ProviderOptions) => AnalyticsProvider;
 
-export { type GoogleAnalyticsProviderOptions, googleAnalytics4 };
+export { type GoogleAnalytics4ProviderOptions, googleAnalytics4 };

package/dist/providers/google-analytics-4.mjs

@@ -1,56 +1,61 @@
+import { defineAnalyticsProvider } from '../index.mjs';
+import 'ua-parser-js';
+
 const DEFAULT_ENGAGEMENT_TIME_IN_MSEC = 100;
-const googleAnalytics4 = (options) => (_, config) => {
-  const send = async (data, eventName, eventProperties) => {
-    const url = new URL(
-      config?.debug ? "/debug/mp/collect" : "/mp/collect",
-      "https://www.google-analytics.com"
-    );
-    if (options.apiSecret)
-      url.searchParams.set("api_secret", options.apiSecret);
-    if (options.measurementId)
-      url.searchParams.set("measurement_id", options.measurementId);
-    const userProperties = {
-      language: data.meta.language,
-      screen: data.meta.screen,
-      ...data.user.properties
-    };
-    const mappedUserProperties = Object.fromEntries(
-      Object.entries(userProperties).map(([name, value]) => [
-        name,
-        value == null ? void 0 : { value }
-      ])
-    );
-    await fetch(url.href, {
-      method: "POST",
-      body: JSON.stringify({
-        client_id: data.user.id,
-        consent: {
-          ad_user_data: "DENIED",
-          ad_personalization: "DENIED"
-        },
-        user_properties: mappedUserProperties,
-        events: [
-          {
-            name: eventName,
-            params: {
-              session_id: data.meta.sessionId,
-              engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
-              ...eventProperties
+const googleAnalytics4 = defineAnalyticsProvider(
+  (_, config, options) => {
+    const send = async (data, eventName, eventProperties) => {
+      const url = new URL(
+        config?.debug ? "/debug/mp/collect" : "/mp/collect",
+        "https://www.google-analytics.com"
+      );
+      if (options.apiSecret)
+        url.searchParams.set("api_secret", options.apiSecret);
+      if (options.measurementId)
+        url.searchParams.set("measurement_id", options.measurementId);
+      const userProperties = {
+        language: data.meta.language,
+        screen: data.meta.screen,
+        ...data.user.properties
+      };
+      const mappedUserProperties = Object.fromEntries(
+        Object.entries(userProperties).map(([name, value]) => [
+          name,
+          value == null ? void 0 : { value }
+        ])
+      );
+      await fetch(url.href, {
+        method: "POST",
+        body: JSON.stringify({
+          client_id: data.user.id,
+          consent: {
+            ad_user_data: "DENIED",
+            ad_personalization: "DENIED"
+          },
+          user_properties: mappedUserProperties,
+          events: [
+            {
+              name: eventName,
+              params: {
+                session_id: data.meta.sessionId,
+                engagement_time_msec: DEFAULT_ENGAGEMENT_TIME_IN_MSEC,
+                ...eventProperties
+              }
             }
-          }
-        ]
-      })
-    });
-  };
-  return {
-    identify: () => Promise.resolve(),
-    // No-op, user data uploaded in page/track
-    page: (event) => send(event, "page_view", {
-      page_title: event.page.title,
-      page_location: event.page.location
-    }),
-    track: (event) => send(event, event.event.name, event.event.properties)
-  };
-};
+          ]
+        })
+      });
+    };
+    return {
+      identify: () => Promise.resolve(),
+      // No-op, user data uploaded in page/track
+      page: (event) => send(event, "page_view", {
+        page_title: event.page.title,
+        page_location: event.page.location
+      }),
+      track: (event) => send(event, event.event.name, event.event.properties)
+    };
+  }
+);
 
 export { googleAnalytics4 };

package/dist/providers/umami.d.mts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.mjs';
+import { AnalyticsProvider } from '../types.mjs';
 
 interface UmamiProviderOptions {
-    baseUrl: string;
+    apiUrl: string;
     websiteId: string;
-    hostname: string;
+    domain: string;
 }
 declare const umami: (options: UmamiProviderOptions) => AnalyticsProvider;
 

package/dist/providers/umami.d.ts

@@ -1,9 +1,9 @@
-import { b as AnalyticsProvider } from '../shared/analytics.2893a879.js';
+import { AnalyticsProvider } from '../types.js';
 
 interface UmamiProviderOptions {
-    baseUrl: string;
+    apiUrl: string;
     websiteId: string;
-    hostname: string;
+    domain: string;
 }
 declare const umami: (options: UmamiProviderOptions) => AnalyticsProvider;
 

package/dist/providers/umami.mjs

@@ -1,44 +1,54 @@
-const umami = (options) => (analytics, config) => {
-  const send = (payload) => fetch(`${options.baseUrl}/api/send`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({ type: "event", payload })
-  });
-  return {
-    identify: () => Promise.resolve(),
-    // No-op, user data uploaded in page/track
-    page: async (event) => {
-      await send({
-        name: "page_view",
-        website: options.websiteId,
-        url: event.page.url,
-        hostname: options.hostname,
-        language: event.meta.language ?? "",
-        referrer: event.meta.referrer ?? "",
-        screen: event.meta.screen ?? "",
-        title: event.page.title ?? "<blank>",
-        data: event.user.properties
-      });
-    },
-    track: async (event) => {
-      await send({
-        name: event.event.name,
-        website: options.websiteId,
-        url: event.meta.url ?? "/",
-        title: "<blank>",
-        hostname: options.hostname,
-        language: event.meta.language ?? "",
-        referrer: event.meta.referrer ?? "",
-        screen: event.meta.screen ?? "",
-        data: {
-          ...event.event.properties,
-          ...event.user.properties
-        }
+import { defineAnalyticsProvider } from '../index.mjs';
+import 'ua-parser-js';
+
+const umami = defineAnalyticsProvider(
+  (_, config, options) => {
+    const send = (payload) => {
+      if (config.debug) {
+        console.debug("[@wxt-dev/analytics] Sending event to Umami:", payload);
+      }
+      return fetch(`${options.apiUrl}/send`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ type: "event", payload })
       });
-    }
-  };
-};
+    };
+    return {
+      identify: () => Promise.resolve(),
+      // No-op, user data uploaded in page/track
+      page: async (event) => {
+        await send({
+          name: "page_view",
+          website: options.websiteId,
+          url: event.page.url,
+          hostname: options.domain,
+          language: event.meta.language ?? "",
+          referrer: event.meta.referrer ?? "",
+          screen: event.meta.screen ?? "",
+          title: event.page.title ?? "<blank>",
+          data: event.user.properties
+        });
+      },
+      track: async (event) => {
+        await send({
+          name: event.event.name,
+          website: options.websiteId,
+          url: event.meta.url ?? "/",
+          title: "<blank>",
+          hostname: options.domain,
+          language: event.meta.language ?? "",
+          referrer: event.meta.referrer ?? "",
+          screen: event.meta.screen ?? "",
+          data: {
+            ...event.event.properties,
+            ...event.user.properties
+          }
+        });
+      }
+    };
+  }
+);
 
 export { umami };

package/dist/{shared/analytics.2893a879.d.ts → types.d.mts}

@@ -45,7 +45,7 @@ type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
     page: (event: AnalyticsPageViewEvent) => Promise<void>;
     /** Upload a custom event */
     track: (event: AnalyticsTrackEvent) => Promise<void>;
-    /** Upload or save information about the user */
+    /** Upload information about the user */
     identify: (event: BaseAnalyticsEvent) => Promise<void>;
 };
 interface BaseAnalyticsEvent {
@@ -86,4 +86,4 @@ interface AnalyticsTrackEvent extends BaseAnalyticsEvent {
     };
 }
 
-export type { AnalyticsConfig as A, Analytics as a, AnalyticsProvider as b };
+export type { Analytics, AnalyticsConfig, AnalyticsEventMetadata, AnalyticsPageInfo, AnalyticsPageViewEvent, AnalyticsProvider, AnalyticsStorageItem, AnalyticsTrackEvent, BaseAnalyticsEvent };

package/dist/{shared/analytics.2893a879.d.mts → types.d.ts}

@@ -45,7 +45,7 @@ type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
     page: (event: AnalyticsPageViewEvent) => Promise<void>;
     /** Upload a custom event */
     track: (event: AnalyticsTrackEvent) => Promise<void>;
-    /** Upload or save information about the user */
+    /** Upload information about the user */
     identify: (event: BaseAnalyticsEvent) => Promise<void>;
 };
 interface BaseAnalyticsEvent {
@@ -86,4 +86,4 @@ interface AnalyticsTrackEvent extends BaseAnalyticsEvent {
     };
 }
 
-export type { AnalyticsConfig as A, Analytics as a, AnalyticsProvider as b };
+export type { Analytics, AnalyticsConfig, AnalyticsEventMetadata, AnalyticsPageInfo, AnalyticsPageViewEvent, AnalyticsProvider, AnalyticsStorageItem, AnalyticsTrackEvent, BaseAnalyticsEvent };

package/dist/types.mjs

@@ -0,0 +1 @@
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxt-dev/analytics",
-  "version": "0.2.7",
+  "version": "0.4.0",
   "description": "Add analytics to your web extension",
   "repository": {
     "type": "git",
@@ -14,9 +14,16 @@
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
     },
-    "./client": {
-      "types": "./dist/client.d.mts",
-      "default": "./dist/client.mjs"
+    "./module": {
+      "types": "./dist/module.d.mts",
+      "default": "./dist/module.mjs"
+    },
+    "./background-plugin": {
+      "types": "./dist/background-plugin.d.mts",
+      "default": "./dist/background-plugin.mjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.mts"
     },
     "./providers/google-analytics-4": {
       "types": "./dist/providers/google-analytics-4.d.mts",
@@ -33,17 +40,16 @@
     "dist"
   ],
   "peerDependencies": {
-    "wxt": ">=0.18.14"
+    "wxt": ">=0.19.23"
   },
   "devDependencies": {
-    "@aklinker1/check": "^1.3.1",
+    "@aklinker1/check": "^1.4.5",
     "@types/chrome": "^0.0.268",
     "@types/ua-parser-js": "^0.7.39",
-    "prettier": "^3.3.2",
-    "publint": "^0.2.8",
-    "typescript": "^5.5.2",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
     "unbuild": "^2.0.0",
-    "wxt": "0.19.13"
+    "wxt": "0.19.23"
   },
   "dependencies": {
     "ua-parser-js": "^1.0.38"
@@ -51,7 +57,7 @@
   "scripts": {
     "dev": "buildc --deps-only -- wxt",
     "dev:build": "buildc --deps-only -- wxt build",
-    "check": "buildc --deps-only -- check",
+    "check": "pnpm build && check",
     "build": "buildc -- unbuild"
   }
 }

package/dist/client.d.mts

@@ -1,5 +0,0 @@
-import { A as AnalyticsConfig, a as Analytics } from './shared/analytics.2893a879.mjs';
-
-declare function createAnalytics(config?: AnalyticsConfig): Analytics;
-
-export { createAnalytics };

package/dist/client.d.ts

@@ -1,5 +0,0 @@
-import { A as AnalyticsConfig, a as Analytics } from './shared/analytics.2893a879.js';
-
-declare function createAnalytics(config?: AnalyticsConfig): Analytics;
-
-export { createAnalytics };

package/dist/client.mjs

@@ -1,201 +0,0 @@
-import { UAParser } from 'ua-parser-js';
-
-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'."
-    );
-  }
-  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("[analytics] identify", event);
-      if (await enabled.getValue()) {
-        await Promise.allSettled(
-          providers.map((provider) => provider.identify(event))
-        );
-      } else if (config?.debug) {
-        console.debug(
-          "[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("[analytics] page", event);
-      if (await enabled.getValue()) {
-        await Promise.allSettled(
-          providers.map((provider) => provider.page(event))
-        );
-      } else if (config?.debug) {
-        console.debug("[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("[analytics] track", event);
-      if (await enabled.getValue()) {
-        await Promise.allSettled(
-          providers.map((provider) => provider.track(event))
-        );
-      } else if (config?.debug) {
-        console.debug("[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"
-]);
-
-export { createAnalytics };