wxt/packages/analytics

WXT Analytics

Report analytics events from your web extension extension.

Supported Analytics Providers

• Google Analytics 4 (Measurement Protocol)
• Umami

Install With WXT

1. Install the NPM package:

   pnpm i @wxt-dev/analytics
   

2. In your wxt.config.ts, add the WXT module:

   export default defineConfig({
     modules: ['@wxt-dev/analytics/module'],
   });
   

3. In your <srcDir>/app.config.ts, add a provider:

   // <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:

   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:

   pnpm i @wxt-dev/analytics
   

2. Create an analytics instance:

   // 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:

   // background.ts
   import './utils/analytics';
   

4. Then use your analytics instance to report events:

   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 is an alternative to GTag for reporting events to Google Analytics for MV3 extensions.

Why use the Measurement Protocol instead of GTag?

Follow Google's documentation to obtain your credentials and put them in your .env file:

WXT_GA_API_SECRET='...'

Then add the googleAnalytics4 provider to your <srcDir>/app.config.ts file:

import { googleAnalytics4 } from '@wxt-dev/analytics/providers/google-analytics-4';

export default defineAppConfig({
  analytics: {
    providers: [
      googleAnalytics4({
        apiSecret: import.meta.env.WXT_GA_API_SECRET,
        measurementId: '...',
      }),
    ],
  },
});

Umami

Umami is a privacy-first, open source analytics platform.

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.

After the website has been created, save the website ID and domain to your .env file:

WXT_UMAMI_WEBSITE_ID='...'
WXT_UMAMI_DOMAIN='...'

Then add the umami provider to your <srcDir>/app.config.ts file:

import { umami } from '@wxt-dev/analytics/providers/umami';

export default defineAppConfig({
  analytics: {
    providers: [
      umami({
        apiUrl: 'https://<your-umami-instance>/api',
        websiteId: import.meta.env.WXT_UMAMI_WEBSITE_ID,
        domain: import.meta.env.WXT_UMAMI_DOMAIN,
      }),
    ],
  },
});

Custom Provider

If your analytics platform is not supported, you can provide an implementation of the AnalyticsProvider type in your app.config.ts instead:

import { defineAnalyticsProvider } from '@wxt-dev/analytics/client';

interface CustomAnalyticsOptions {
  // ...
}

const customAnalytics = defineAnalyticsProvider<CustomAnalyticsOptions>(
  (analytics, analyticsConfig, providerOptions) => {
    // ...
  },
);

export default defineAppConfig({
  analytics: {
    providers: [
      customAnalytics({
        // ...
      }),
    ],
  },
});

Example AnalyticsProvider implementations can be found at ./modules/analytics/providers.