@wxt-dev/analytics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Aaron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# WXT Analytics
+
+Add analytics, like google analytics, to your WXT extension.
+
+## Supported Analytics Providers
+
+- Google Analytics (Measurement Protocol)
+- Umami
+
+## Installation
+
+Install the NPM package:
+
+```bash
+pnpm i @wxt-dev/analytics
+```
+
+Then add the module to your `wxt.config.ts` file:
+
+```ts
+export default defineConfig({
+  modules: ['@wxt-dev/analytics'],
+});
+```
+
+Create an `app.config.ts` file and fill out the required config:
+
+```ts
+// <srcDir>/app.config.ts
+export default defineAppConfig({
+  analytics: {
+    debug: true,
+    providers: [
+      // ...
+    ],
+  },
+});
+```
+
+Then use the `analytics` import to report events:
+
+```ts
+import { analytics } from '@wxt-dev/analytics';
+
+await analytics.track('some-event');
+await analytics.page();
+await analytics.identify('some-user-id');
+```
+
+## Providers
+
+### Google Analytics (Measurement Protocol)
+
+Follow [Google's documentation](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#setup-credentials) to obtain your credentials:
+
+```ts
+import { googleAnalytics4 } from '@wxt-dev/analytics/providers/google-analytics-4';
+
+export default defineAppConfig({
+  analytics: {
+    providers: [
+      googleAnalytics4({
+        apiSecret: '...',
+        measurementId: '...',
+      }),
+    ],
+  },
+});
+```
+
+> [Why use the Measurement Protocol instead of GTag?](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#measurement-protocol)
+
+### Umami
+
+```ts
+import { umami } from '@wxt-dev/analytics/providers/umami';
+
+export default defineAppConfig({
+  analytics: {
+    providers: [
+      umami({
+        baseUrl: 'https://your-domain.com',
+        websiteId: '...',
+        hostname: '...',
+      }),
+    ],
+  },
+});
+```

package/dist/client.d.mts

@@ -0,0 +1,6 @@
+import { a as Analytics } from './shared/analytics.c704a57b.mjs';
+
+declare let analytics: Analytics;
+declare const _default: any;
+
+export { analytics, _default as default };

package/dist/client.d.ts

@@ -0,0 +1,6 @@
+import { a as Analytics } from './shared/analytics.c704a57b.js';
+
+declare let analytics: Analytics;
+declare const _default: any;
+
+export { analytics, _default as default };

package/dist/client.mjs

@@ -0,0 +1,179 @@
+import { defineWxtPlugin } from 'wxt/sandbox';
+import uaParser from 'ua-parser-js';
+
+let analytics;
+const ANALYTICS_PORT = "wxt-analytics";
+const interactiveTags = /* @__PURE__ */ new Set(["A", "BUTTON", "INPUT", "SELECT", "TEXTAREA"]);
+const interactiveRoles = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "checkbox",
+  "menuitem",
+  "tab",
+  "radio"
+]);
+const client = defineWxtPlugin(() => {
+  const isBackground = globalThis.window == null;
+  analytics = isBackground ? createBackgroundAnalytics() : createAnalyticsForwarder();
+});
+function createAnalyticsForwarder() {
+  const port = browser.runtime.connect({ name: ANALYTICS_PORT });
+  const sessionId = Date.now();
+  const getMetadata = () => ({
+    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
+  });
+  const methodForwarder = (fn) => (...args) => port.postMessage({ fn, args: [...args, getMetadata()] });
+  const analytics2 = {
+    identify: methodForwarder("identify"),
+    page: methodForwarder("page"),
+    track: methodForwarder("track"),
+    setEnabled: methodForwarder("setEnabled"),
+    autoTrack: (root) => {
+      const onClick = (event) => {
+        const element = event.target;
+        if (!element || !interactiveTags.has(element.tagName) && !interactiveRoles.has(element.getAttribute("role")))
+          return;
+        void analytics2.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 analytics2;
+}
+function createBackgroundAnalytics() {
+  const config = useAppConfig().analytics;
+  const userIdStorage = config?.userId ?? storage.defineItem("local:wxt-analytics:user-id");
+  const userPropertiesStorage = config?.userProperties ?? storage.defineItem(
+    "local:wxt-analytics:user-properties",
+    { defaultValue: {} }
+  );
+  const enabled = config?.enabled ?? storage.defineItem("local:wxt-analytics:enabled", {
+    defaultValue: false
+  });
+  const platformInfo = browser.runtime.getPlatformInfo();
+  const userAgent = uaParser();
+  let userId = Promise.resolve(userIdStorage.getValue()).then(
+    (id) => id ?? globalThis.crypto.randomUUID()
+  );
+  let userProperties = userPropertiesStorage.getValue();
+  const manifest = browser.runtime.getManifest();
+  const getBaseEvent = async (meta = {
+    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
+  }) => {
+    const platform = await platformInfo;
+    return {
+      meta: {
+        sessionId: meta.sessionId,
+        timestamp: meta.timestamp,
+        screen: meta.screen,
+        referrer: meta.referrer,
+        language: meta.language
+      },
+      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 analytics2 = {
+    identify: async (newUserId, newUserProperties = {}, forwardMeta) => {
+      userId = Promise.resolve(newUserId);
+      userProperties = Promise.resolve(newUserProperties);
+      await Promise.all([
+        userIdStorage.setValue?.(newUserId),
+        userPropertiesStorage.setValue?.(newUserProperties)
+      ]);
+      const event = await getBaseEvent(forwardMeta);
+      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] Disabled, identify() not called");
+      }
+    },
+    page: async (url, forwardMeta) => {
+      const baseEvent = await getBaseEvent(forwardMeta);
+      const event = {
+        ...baseEvent,
+        page: { url }
+      };
+      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] Disabled, page() not called");
+      }
+    },
+    track: async (eventName, eventProperties, forwardMeta) => {
+      const baseEvent = await getBaseEvent(forwardMeta);
+      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] Disabled, track() not called");
+      }
+    },
+    setEnabled: async (newEnabled) => {
+      await enabled.setValue?.(newEnabled);
+    },
+    autoTrack: () => {
+      return () => {
+      };
+    }
+  };
+  const providers = config?.providers?.map((provider) => provider(analytics2, config)) ?? [];
+  chrome.runtime.onConnect.addListener((port) => {
+    if (port.name === ANALYTICS_PORT) {
+      port.onMessage.addListener(({ fn, args }) => {
+        void analytics2[fn]?.(...args);
+      });
+    }
+  });
+  return analytics2;
+}
+
+export { analytics, client as default };

package/dist/index.d.mts

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

package/dist/index.d.ts

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

package/dist/index.mjs

@@ -0,0 +1,24 @@
+import 'wxt';
+import 'wxt/sandbox';
+import { defineWxtModule, addWxtPlugin } from 'wxt/modules';
+import { resolve } from 'node:path';
+
+const pluginId = "@wxt-dev/analytics/client" ;
+const index = defineWxtModule({
+  name: "analytics",
+  imports: [{ name: "analytics", from: pluginId }],
+  setup(wxt) {
+    addWxtPlugin(
+      wxt,
+      resolve(__dirname, "client.mjs" )
+    );
+    wxt.hooks.hook("build:manifestGenerated", (_, manifest) => {
+      manifest.permissions ?? (manifest.permissions = []);
+      if (!manifest.permissions.includes("storage")) {
+        manifest.permissions.push("storage");
+      }
+    });
+  }
+});
+
+export { index as default };

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

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

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

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

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

@@ -0,0 +1,56 @@
+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
+            }
+          }
+        ]
+      })
+    });
+  };
+  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

@@ -0,0 +1,10 @@
+import { b as AnalyticsProvider } from '../shared/analytics.c704a57b.mjs';
+
+interface UmamiProviderOptions {
+    baseUrl: string;
+    websiteId: string;
+    hostname: string;
+}
+declare const umami: (options: UmamiProviderOptions) => AnalyticsProvider;
+
+export { type UmamiProviderOptions, umami };

package/dist/providers/umami.d.ts

@@ -0,0 +1,10 @@
+import { b as AnalyticsProvider } from '../shared/analytics.c704a57b.js';
+
+interface UmamiProviderOptions {
+    baseUrl: string;
+    websiteId: string;
+    hostname: string;
+}
+declare const umami: (options: UmamiProviderOptions) => AnalyticsProvider;
+
+export { type UmamiProviderOptions, umami };

package/dist/providers/umami.mjs

@@ -0,0 +1,44 @@
+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
+        }
+      });
+    }
+  };
+};
+
+export { umami };

package/dist/shared/analytics.c704a57b.d.mts

@@ -0,0 +1,86 @@
+interface Analytics {
+    /** Report a page change */
+    page: (url: string) => void;
+    /** Report a custom event */
+    track: (eventName: string, eventProperties: Record<string, string>) => void;
+    /** 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` */
+    setEnabled: (enabled: boolean) => void;
+}
+interface AnalyticsConfig {
+    /**
+     * Array of providers to send analytics to.
+     */
+    providers: AnalyticsProvider[];
+    /**
+     * Enable debug logs and other provider-specific debugging features.
+     */
+    debug?: boolean;
+    /**
+     * Extension version, defaults to `browser.runtime.getManifest().version`.
+     */
+    version?: string;
+    /**
+     * Configure how the enabled flag is persisted
+     */
+    enabled?: AnalyticsStorageItemConfig<boolean>;
+    /**
+     * Configure how the user Id is persisted
+     */
+    userId?: AnalyticsStorageItemConfig<string>;
+    /**
+     * Configure how user properties are persisted
+     */
+    userProperties?: AnalyticsStorageItemConfig<Record<string, string>>;
+}
+interface AnalyticsStorageItemConfig<T> {
+    getValue: () => T | Promise<T>;
+    setValue?: (newValue: T) => void | Promise<void>;
+}
+type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
+    /** Upload a page view event */
+    page: (event: AnalyticsPageViewEvent) => Promise<void>;
+    /** Upload a custom event */
+    track: (event: AnalyticsTrackEvent) => Promise<void>;
+    /** Upload or save information about the user */
+    identify: (event: BaseAnalyticsEvent) => Promise<void>;
+};
+interface BaseAnalyticsEvent {
+    meta: {
+        /** Identifier of the session the event was fired from */
+        sessionId: number | undefined;
+        /** `Date.now()` of when the event was reported */
+        timestamp: number;
+        /** `"1920x1080"` */
+        screen?: string;
+        /** `document.referrer` */
+        referrer?: string;
+        /** `navigator.language` */
+        language?: string;
+        /** `location.href` */
+        url?: string;
+    };
+    user: {
+        id: string;
+        properties: Record<string, string | undefined>;
+    };
+}
+interface AnalyticsPageInfo {
+    url: string;
+    title?: string;
+    location?: string;
+}
+interface AnalyticsPageViewEvent extends BaseAnalyticsEvent {
+    page: AnalyticsPageInfo;
+}
+interface AnalyticsTrackEvent extends BaseAnalyticsEvent {
+    event: {
+        name: string;
+        properties?: Record<string, string>;
+    };
+}
+
+export type { AnalyticsConfig as A, Analytics as a, AnalyticsProvider as b };

package/dist/shared/analytics.c704a57b.d.ts

@@ -0,0 +1,86 @@
+interface Analytics {
+    /** Report a page change */
+    page: (url: string) => void;
+    /** Report a custom event */
+    track: (eventName: string, eventProperties: Record<string, string>) => void;
+    /** 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` */
+    setEnabled: (enabled: boolean) => void;
+}
+interface AnalyticsConfig {
+    /**
+     * Array of providers to send analytics to.
+     */
+    providers: AnalyticsProvider[];
+    /**
+     * Enable debug logs and other provider-specific debugging features.
+     */
+    debug?: boolean;
+    /**
+     * Extension version, defaults to `browser.runtime.getManifest().version`.
+     */
+    version?: string;
+    /**
+     * Configure how the enabled flag is persisted
+     */
+    enabled?: AnalyticsStorageItemConfig<boolean>;
+    /**
+     * Configure how the user Id is persisted
+     */
+    userId?: AnalyticsStorageItemConfig<string>;
+    /**
+     * Configure how user properties are persisted
+     */
+    userProperties?: AnalyticsStorageItemConfig<Record<string, string>>;
+}
+interface AnalyticsStorageItemConfig<T> {
+    getValue: () => T | Promise<T>;
+    setValue?: (newValue: T) => void | Promise<void>;
+}
+type AnalyticsProvider = (analytics: Analytics, config: AnalyticsConfig) => {
+    /** Upload a page view event */
+    page: (event: AnalyticsPageViewEvent) => Promise<void>;
+    /** Upload a custom event */
+    track: (event: AnalyticsTrackEvent) => Promise<void>;
+    /** Upload or save information about the user */
+    identify: (event: BaseAnalyticsEvent) => Promise<void>;
+};
+interface BaseAnalyticsEvent {
+    meta: {
+        /** Identifier of the session the event was fired from */
+        sessionId: number | undefined;
+        /** `Date.now()` of when the event was reported */
+        timestamp: number;
+        /** `"1920x1080"` */
+        screen?: string;
+        /** `document.referrer` */
+        referrer?: string;
+        /** `navigator.language` */
+        language?: string;
+        /** `location.href` */
+        url?: string;
+    };
+    user: {
+        id: string;
+        properties: Record<string, string | undefined>;
+    };
+}
+interface AnalyticsPageInfo {
+    url: string;
+    title?: string;
+    location?: string;
+}
+interface AnalyticsPageViewEvent extends BaseAnalyticsEvent {
+    page: AnalyticsPageInfo;
+}
+interface AnalyticsTrackEvent extends BaseAnalyticsEvent {
+    event: {
+        name: string;
+        properties?: Record<string, string>;
+    };
+}
+
+export type { AnalyticsConfig as A, Analytics as a, AnalyticsProvider as b };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@wxt-dev/analytics",
+  "version": "0.1.0",
+  "description": "Add analytics to your web extension",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wxt-dev/wxt.git",
+    "directory": "packages/analytics"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.mts",
+      "default": "./dist/client.mjs"
+    },
+    "./providers/google-analytics-4": {
+      "types": "./dist/providers/google-analytics-4.d.mts",
+      "default": "./dist/providers/google-analytics-4.mjs"
+    },
+    "./providers/umami": {
+      "types": "./dist/providers/umami.d.mts",
+      "default": "./dist/providers/umami.mjs"
+    }
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "wxt": ">=0.18.12"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^1.3.1",
+    "@types/chrome": "^0.0.268",
+    "@types/ua-parser-js": "^0.7.39",
+    "prettier": "^3.3.2",
+    "publint": "^0.2.8",
+    "typescript": "^5.5.2",
+    "unbuild": "^2.0.0",
+    "wxt": "0.18.13"
+  },
+  "dependencies": {
+    "ua-parser-js": "^1.0.38"
+  },
+  "scripts": {
+    "dev": "buildc --deps-only -- wxt",
+    "dev:build": "buildc --deps-only -- wxt build",
+    "check": "buildc --deps-only -- check",
+    "build": "buildc -- unbuild"
+  }
+}