From 6fb1463a3219902b72193516e2ccb513e2b32c42 Mon Sep 17 00:00:00 2001 From: Aaron Date: Sun, 29 Dec 2024 19:10:19 -0600 Subject: [PATCH] defineAnalyticsProvider and updated umami config --- packages/analytics/README.md | 101 ++++++++++++++---- packages/analytics/app.config.ts | 4 +- packages/analytics/build.config.ts | 3 +- .../analytics/modules/analytics/client.ts | 1 + .../modules/analytics/providers/umami.ts | 20 ++-- packages/analytics/package.json | 2 +- packages/analytics/wxt.config.ts | 5 - pnpm-lock.yaml | 16 +-- 8 files changed, 103 insertions(+), 49 deletions(-) diff --git a/packages/analytics/README.md b/packages/analytics/README.md index 17e5c06a..14f52ad1 100644 --- a/packages/analytics/README.md +++ b/packages/analytics/README.md @@ -37,7 +37,7 @@ export default defineAppConfig({ }); ``` -Then use the `analytics` import to report events: +Then use the `#analytics` module to report events: ```ts import { analytics } from '#analytics'; @@ -52,39 +52,96 @@ analytics.autoTrack(document.body); ### 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: - -```ts -import { googleAnalytics4 } from '@wxt-dev/analytics/providers/google-analytics-4'; - -export default defineAppConfig({ - analytics: { - providers: [ - googleAnalytics4({ - apiSecret: '...', - measurementId: '...', - }), - ], - }, -}); -``` +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. > [Why use the Measurement Protocol instead of GTag?](https://developer.chrome.com/docs/extensions/how-to/integrate/google-analytics-4#measurement-protocol) +1. Add the module to your config: + ```ts + export default defineConfig({ + modules: ['@wxt-dev/analytics'], + }); + ``` +2. 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='...' + ``` +3. Add the `googleAnalytics4` provider to your `/app.config.ts` file: + + ```ts + 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](https://umami.is/) is a privacy-first, open source analytics platform. + +1. Add the module to your config: + ```ts + 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: + ```dotenv + WXT_UMAMI_WEBSITE_ID=... + WXT_UMAMI_DOMAIN=... + ``` +3. Add the `umami` provider to your `/app.config.ts` file: + + ```ts + import { umami } from '@wxt-dev/analytics/providers/umami'; + + export default defineAppConfig({ + analytics: { + providers: [ + umami({ + apiUrl: 'https:///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: + ```ts -import { umami } from '@wxt-dev/analytics/providers/umami'; +import { defineAnalyticsProvider } from '@wxt-dev/analytics/client'; + +interface CustomAnalyticsOptions { + // ... +} + +const customAnalytics = defineAnalyticsProvider( + (analytics, analyticsConfig, providerOptions) => { + // ... + }, +); export default defineAppConfig({ analytics: { providers: [ - umami({ - baseUrl: 'https://your-domain.com', - websiteId: '...', - hostname: '...', + customAnalytics({ + // ... }), ], }, }); ``` + +For example `AnalyticsProvider` implementations, see [`./modules/analytics/providers`](https://github.com/wxt-dev/wxt/tree/main/packages/analytics/modules/analytics/providers). diff --git a/packages/analytics/app.config.ts b/packages/analytics/app.config.ts index 37df7da3..757be284 100644 --- a/packages/analytics/app.config.ts +++ b/packages/analytics/app.config.ts @@ -11,8 +11,8 @@ export default defineAppConfig({ measurementId: '...', }), umami({ - baseUrl: 'https://umami.aklinker1.io', - hostname: 'analytics.wxt.dev', + apiUrl: 'https://umami.aklinker1.io/api', + domain: 'analytics.wxt.dev', websiteId: '8f1c2aa4-fad3-406e-a5b2-33e8d4501716', }), ], diff --git a/packages/analytics/build.config.ts b/packages/analytics/build.config.ts index 850b198d..fbdb6c57 100644 --- a/packages/analytics/build.config.ts +++ b/packages/analytics/build.config.ts @@ -8,11 +8,12 @@ export default defineBuildConfig({ entries: [ 'index.ts', 'client.ts', + 'types.ts', 'providers/google-analytics-4.ts', 'providers/umami.ts', ], replace: { - __PACKAGED__: 'true', + 'ipmort.meta.env.NPM': 'true', }, declaration: true, }); diff --git a/packages/analytics/modules/analytics/client.ts b/packages/analytics/modules/analytics/client.ts index 1e8dc0b0..fcdac837 100644 --- a/packages/analytics/modules/analytics/client.ts +++ b/packages/analytics/modules/analytics/client.ts @@ -8,6 +8,7 @@ import type { BaseAnalyticsEvent, AnalyticsEventMetadata, } from './types'; +export * from './client-utils'; const ANALYTICS_PORT = '@wxt-dev/analytics'; diff --git a/packages/analytics/modules/analytics/providers/umami.ts b/packages/analytics/modules/analytics/providers/umami.ts index c1deec3d..fc99487f 100644 --- a/packages/analytics/modules/analytics/providers/umami.ts +++ b/packages/analytics/modules/analytics/providers/umami.ts @@ -1,16 +1,15 @@ -import type { AnalyticsProvider } from '../types'; +import { defineAnalyticsProvider } from '../client-utils'; export interface UmamiProviderOptions { - baseUrl: string; + apiUrl: string; websiteId: string; - hostname: string; + domain: string; } -export const umami = - (options: UmamiProviderOptions): AnalyticsProvider => - (analytics, config) => { +export const umami = defineAnalyticsProvider( + (analytics, config, options) => { const send = (payload: UmamiPayload) => - fetch(`${options.baseUrl}/api/send`, { + fetch(`${options.apiUrl}/send`, { method: 'POST', headers: { 'Content-Type': 'application/json', @@ -25,7 +24,7 @@ export const umami = name: 'page_view', website: options.websiteId, url: event.page.url, - hostname: options.hostname, + hostname: options.domain, language: event.meta.language ?? '', referrer: event.meta.referrer ?? '', screen: event.meta.screen ?? '', @@ -39,7 +38,7 @@ export const umami = website: options.websiteId, url: event.meta.url ?? '/', title: '', - hostname: options.hostname, + hostname: options.domain, language: event.meta.language ?? '', referrer: event.meta.referrer ?? '', screen: event.meta.screen ?? '', @@ -50,7 +49,8 @@ export const umami = }); }, }; - }; + }, +); interface UmamiPayload { hostname?: string; diff --git a/packages/analytics/package.json b/packages/analytics/package.json index 518c40dc..d1facd75 100644 --- a/packages/analytics/package.json +++ b/packages/analytics/package.json @@ -1,6 +1,6 @@ { "name": "@wxt-dev/analytics", - "version": "0.2.8", + "version": "0.3.0", "description": "Add analytics to your web extension", "repository": { "type": "git", diff --git a/packages/analytics/wxt.config.ts b/packages/analytics/wxt.config.ts index 8b3254ec..f4b6f665 100644 --- a/packages/analytics/wxt.config.ts +++ b/packages/analytics/wxt.config.ts @@ -8,9 +8,4 @@ export default defineConfig({ manifest: { name: 'Analytics Demo', }, - vite: () => ({ - define: { - __PACKAGED__: 'false', - }, - }), }); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index bda60fea..1553cd1e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -87,11 +87,11 @@ importers: dependencies: ua-parser-js: specifier: ^1.0.38 - version: 1.0.39 + version: 1.0.40 devDependencies: '@aklinker1/check': specifier: ^1.3.1 - version: 1.4.5(typescript@5.6.2) + version: 1.4.5(typescript@5.6.3) '@types/chrome': specifier: ^0.0.268 version: 0.0.268 @@ -103,13 +103,13 @@ importers: version: 3.3.3 publint: specifier: ^0.2.8 - version: 0.2.11 + version: 0.2.12 typescript: specifier: ^5.5.2 - version: 5.6.2 + version: 5.6.3 unbuild: specifier: ^2.0.0 - version: 2.0.0(sass@1.79.4)(typescript@5.6.2) + version: 2.0.0(sass@1.80.7)(typescript@5.6.3) wxt: specifier: workspace:* version: link:../wxt @@ -4805,8 +4805,8 @@ packages: engines: {node: '>=14.17'} hasBin: true - ua-parser-js@1.0.39: - resolution: {integrity: sha512-k24RCVWlEcjkdOxYmVJgeD/0a1TiSpqLg+ZalVGV9lsnr4yqu0w7tX/x2xX6G4zpkgQnRf89lxuZ1wsbjXM8lw==} + ua-parser-js@1.0.40: + resolution: {integrity: sha512-z6PJ8Lml+v3ichVojCiB8toQJBuwR42ySM4ezjXIqXK3M0HczmKQ3LF4rhU55PfD99KEEXQG6yb7iOMyvYuHew==} hasBin: true ufo@1.5.3: @@ -9489,7 +9489,7 @@ snapshots: typescript@5.6.3: {} - ua-parser-js@1.0.39: {} + ua-parser-js@1.0.40: {} ufo@1.5.3: {}