wxt/packages/analytics

WXT Analytics

Add analytics, like google analytics, to your WXT extension.

Supported Analytics Providers

• Google Analytics 4 (Measurement Protocol)
• Umami

Installation

Install the NPM package:

pnpm i @wxt-dev/analytics

Then add the module to your wxt.config.ts file:

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

Create an app.config.ts file and fill out the required config:

// <srcDir>/app.config.ts
export default defineAppConfig({
  analytics: {
    debug: true,
    providers: [
      // ...
    ],
  },
});

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

Finally, you must import the #analytics module in your background:

// entrypoints/background.ts
import '#analytics';

This is because the analytics object sends events and other data to the background for it perform the HTTP request to upload the data.

This also means to view the network requests in devtools, you must look at the background's devtools.

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?

1. Add the module to your config:

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

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

   WXT_GA_API_SECRET='...'
   

3. 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.

1. Add the module to your config:

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

2. In Umami, 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=...
   

3. 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({
        // ...
      }),
    ],
  },
});

For example AnalyticsProvider implementations, see ./modules/analytics/providers.