feat: allow disabling analytics (#303)

* feat: allow disabling analytics

* docs: update analytics changelogs

* fix: singlenton issue with setupAnalytics method

* chore: update readmes

* change setupAnalytics to public instance method and update singleton merge behavior

* fix: skip evm wallet analytics when disabled

* fix: tolerate legacy multichain singleton analytics setup

* docs: clarify analytics enabled changelog entry

* fix: address analytics lint failures

Author: wenfix

README.md

@@ -169,16 +169,16 @@ Host pages integrating MetaMask Connect need to allow a few origins in their [Co
 ### Required
 
 ```
-connect-src wss://mm-sdk-relay.api.cx.metamask.io https://mm-sdk-analytics.api.cx.metamask.io;
+connect-src wss://mm-sdk-relay.api.cx.metamask.io;
 img-src data:;
 ```
 
 - `wss://mm-sdk-relay.api.cx.metamask.io` — the WebSocket URL of the MetaMask relay used for remote connections (mobile, no-extension, etc.). Unavoidable — the relay cannot be proxied or deferred from within the library, and remote connections will fail without it.
-- `https://mm-sdk-analytics.api.cx.metamask.io` — the telemetry endpoint used by `@metamask/analytics`. Required for the connection lifecycle events the SDK emits by default. You can override the host via the `METAMASK_ANALYTICS_ENDPOINT` env var at build time, but some analytics endpoint must be reachable.
 - `img-src data:` — the install/QR-code modal in `@metamask/multichain-ui` embeds the MetaMask fox SVG as a `data:` URI inside the generated QR code. Without this, the QR code will fail to render entirely.
 
 ### Also consider
 
+- **`https://mm-sdk-analytics.api.cx.metamask.io`** — telemetry endpoint used by `@metamask/analytics` when analytics are enabled. Analytics are enabled by default; set `analytics.enabled: false` to disable analytics events and omit this endpoint from `connect-src`.
 - **`style-src 'unsafe-inline'`** — `@metamask/multichain-ui` is built with [Stencil](https://stenciljs.com/), which injects component styles at runtime inside Shadow DOM. Strict CSPs without `'unsafe-inline'` (or an equivalent nonce/hash strategy) may break modal styling.
 - **RPC endpoints you pass to `api.infuraProjectId` / `api.readonlyRPCMap` / `supportedNetworks`** — e.g. `https://*.infura.io`, your own node provider, or a public RPC. These are supplied by your dApp, so add whatever `connect-src` entries match the endpoints you configure.
 - **`https://metamask.app.link` and `metamask://`** — used for mobile deeplinks / universal links. These are top-level navigations and are not normally subject to `connect-src`, but strict CSPs that use `navigate-to` or `form-action` may need to allow them.

packages/analytics/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `analytics.disable()` to stop event collection and clear queued analytics events. ([#303](https://github.com/MetaMask/connect-monorepo/pull/303))
+
 ## [0.5.0]
 
 ### Added

packages/analytics/src/analytics.test.ts

@@ -103,6 +103,56 @@ t.describe('Analytics Integration', () => {
     scope.done();
   });
 
+  t.it('should stop tracking after disable is called', async () => {
+    let captured: EventV2[] = [];
+    scope = nock('http://127.0.0.4')
+      .post('/v2/events', (body) => {
+        captured = body;
+        return true;
+      })
+      .optionally()
+      .reply(
+        200,
+        { status: 'success' },
+        { 'Content-Type': 'application/json' },
+      );
+
+    analytics = new Analytics('http://127.0.0.4');
+    analytics.enable();
+    analytics.disable();
+    analytics.track('mmconnect_initialized', eventProperties);
+
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    t.expect(captured).toEqual([]);
+    scope.done();
+  });
+
+  t.it('should clear queued events when disable is called', async () => {
+    let captured: EventV2[] = [];
+    scope = nock('http://127.0.0.5')
+      .post('/v2/events', (body) => {
+        captured = body;
+        return true;
+      })
+      .optionally()
+      .reply(
+        200,
+        { status: 'success' },
+        { 'Content-Type': 'application/json' },
+      );
+
+    analytics = new Analytics('http://127.0.0.5');
+    analytics.enable();
+    analytics.track('mmconnect_initialized', eventProperties);
+    analytics.disable();
+
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    t.expect(captured).toEqual([]);
+    scope.done();
+  });
+
   t.it('should merge multiple integration_types global updates', async () => {
     let captured: EventV2[] = [];
     scope = nock('http://127.0.0.3')

packages/analytics/src/analytics.ts

@@ -34,6 +34,14 @@ class Analytics {
     this.enabled = true;
   }
 
+  /**
+   * Disables analytics and drops queued events.
+   */
+  public disable(): void {
+    this.enabled = false;
+    this.sender.clear();
+  }
+
   public setGlobalProperty<K extends keyof MMConnectProperties>(
     key: K,
     value: MMConnectProperties[K],

packages/analytics/src/sender.test.ts

@@ -40,6 +40,18 @@ t.describe('Sender', () => {
     t.expect(sendFn).toHaveBeenCalledWith(['event3']);
   });
 
+  t.it(
+    'should clear queued events and cancel the scheduled flush',
+    async () => {
+      sender.enqueue('event1');
+      sender.clear();
+
+      await t.vi.advanceTimersByTimeAsync(50);
+
+      t.expect(sendFn).not.toHaveBeenCalled();
+    },
+  );
+
   t.it(
     'should handle failure (with exponential backoff) and reset base timeout after successful send',
     async () => {

packages/analytics/src/sender.ts

@@ -39,6 +39,18 @@ class Sender<T> {
     this.schedule();
   }
 
+  /**
+   * Clears queued items and cancels the scheduled flush.
+   */
+  public clear(): void {
+    this.batch = [];
+    this.currentTimeoutMs = this.baseTimeoutMs;
+    if (this.timeoutId) {
+      clearTimeout(this.timeoutId);
+      this.timeoutId = null;
+    }
+  }
+
   private schedule(): void {
     // If the batch is not full and there is no scheduled flush, schedule a flush
     if (this.batch.length > 0 && !this.timeoutId) {

packages/connect-evm/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add an `analytics.enabled` option to `createEVMClient()`. Consumers can set it to `false` to disable dapp-side analytics events and wallet correlation metadata. ([#303](https://github.com/MetaMask/connect-monorepo/pull/303))
+
 ## [1.3.1]
 
 ### Fixed

packages/connect-evm/README.md

@@ -165,21 +165,23 @@ Factory function to create a new MetaMask Connect EVM instance.
 
 #### Parameters
 
-| Option                     | Type                                          | Required | Description                                          |
-| -------------------------- | --------------------------------------------- | -------- | ---------------------------------------------------- |
-| `dapp.name`                | `string`                                      | Yes      | Name of your dApp                                    |
-| `api.supportedNetworks`    | `Record<Hex, string>`                         | Yes      | Map of hex chain IDs to RPC URLs                     |
-| `dapp.url`                 | `string`                                      | No       | URL of your dApp                                     |
-| `dapp.iconUrl`             | `string`                                      | No       | Icon URL for your dApp                               |
-| `ui.headless`              | `boolean`                                     | No       | Run without UI (for custom QR implementations)       |
-| `ui.preferExtension`       | `boolean`                                     | No       | Prefer browser extension over mobile (default: true) |
-| `ui.showInstallModal`      | `boolean`                                     | No       | Show installation modal for desktop                  |
-| `mobile.preferredOpenLink` | `(deeplink: string, target?: string) => void` | No       | Custom deeplink handler                              |
-| `mobile.useDeeplink`       | `boolean`                                     | No       | Use `metamask://` instead of universal links         |
-| `transport.extensionId`    | `string`                                      | No       | Custom extension ID                                  |
-| `transport.onNotification` | `(notification: unknown) => void`             | No       | Notification handler                                 |
-| `eventHandlers`            | `Partial<EventHandlers>`                      | No       | Event handlers for provider events                   |
-| `debug`                    | `boolean`                                     | No       | Enable debug logging                                 |
+| Option                      | Type                                          | Required | Description                                                                                                                  |
+| --------------------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `dapp.name`                 | `string`                                      | Yes      | Name of your dApp                                                                                                            |
+| `api.supportedNetworks`     | `Record<Hex, string>`                         | Yes      | Map of hex chain IDs to RPC URLs                                                                                             |
+| `dapp.url`                  | `string`                                      | No       | URL of your dApp                                                                                                             |
+| `dapp.iconUrl`              | `string`                                      | No       | Icon URL for your dApp                                                                                                       |
+| `ui.headless`               | `boolean`                                     | No       | Run without UI (for custom QR implementations)                                                                               |
+| `ui.preferExtension`        | `boolean`                                     | No       | Prefer browser extension over mobile (default: true)                                                                         |
+| `ui.showInstallModal`       | `boolean`                                     | No       | Show installation modal for desktop                                                                                          |
+| `mobile.preferredOpenLink`  | `(deeplink: string, target?: string) => void` | No       | Custom deeplink handler                                                                                                      |
+| `mobile.useDeeplink`        | `boolean`                                     | No       | Use `metamask://` instead of universal links                                                                                 |
+| `analytics.enabled`         | `boolean`                                     | No       | Enables dapp-side analytics. Defaults to `true`; set to `false` to disable analytics events and wallet correlation metadata. |
+| `analytics.integrationType` | `string`                                      | No       | Integration type for analytics                                                                                               |
+| `transport.extensionId`     | `string`                                      | No       | Custom extension ID                                                                                                          |
+| `transport.onNotification`  | `(notification: unknown) => void`             | No       | Notification handler                                                                                                         |
+| `eventHandlers`             | `Partial<EventHandlers>`                      | No       | Event handlers for provider events                                                                                           |
+| `debug`                     | `boolean`                                     | No       | Enable debug logging                                                                                                         |
 
 #### Returns
 

packages/connect-evm/src/connect.test.ts

@@ -9,6 +9,7 @@ type MockCore = MultichainCore & {
   emit: (event: string, ...args: unknown[]) => void;
   _status: ConnectEvmStatus;
   storage: MultichainCore['storage'] & {
+    getAnonId: Mock<() => Promise<string>>;
     adapter: {
       get: Mock<(key: string) => Promise<string | null>>;
       set: Mock<(key: string, value: string) => Promise<void>>;
@@ -93,6 +94,7 @@ function createMockCore(): MockCore {
       onNotification,
     },
     storage: {
+      getAnonId: vi.fn().mockResolvedValue('anon-id'),
       adapter: {
         get: storageGet,
         set: storageSet,
@@ -868,6 +870,31 @@ describe('MetamaskConnectEVM', () => {
       expect(calls).toEqual(['wallet_switchEthereumChain']);
       expect(calls).not.toContain('wallet_addEthereumChain');
     });
+
+    it('does not build wallet action analytics properties when analytics are disabled', async () => {
+      (mockCore as unknown as { options: MultichainCore['options'] }).options =
+        {
+          dapp: {
+            name: 'Test DApp',
+            url: 'https://test.example',
+          },
+          analytics: { enabled: false, integrationType: 'direct' },
+          versions: {},
+        } as MultichainCore['options'];
+      mockCore.transport.sendEip1193Message.mockResolvedValue({
+        result: null,
+        id: 1,
+        jsonrpc: '2.0' as const,
+      });
+
+      await client.switchChain({ chainId: '0x89' });
+
+      expect(mockCore.storage.getAnonId).not.toHaveBeenCalled();
+      expect(mockCore.transport.sendEip1193Message).toHaveBeenCalledWith({
+        method: 'wallet_switchEthereumChain',
+        params: [{ chainId: '0x89' }],
+      });
+    });
   });
 
   describe('#requestInterceptor', () => {

packages/connect-evm/src/connect.ts

@@ -48,6 +48,16 @@ declare const __PACKAGE_VERSION__: string | undefined;
 const DEFAULT_CHAIN_ID = '0x1';
 const CHAIN_STORE_KEY = 'cache_eth_chainId';
 
+/**
+ * Checks whether dapp-side analytics are enabled for the multichain core.
+ *
+ * @param options - Current multichain options.
+ * @returns Whether analytics events should be collected and sent.
+ */
+function isAnalyticsEnabled(options: MultichainOptions | undefined): boolean {
+  return options?.analytics?.enabled !== false;
+}
+
 /** The options for the connect method */
 type ConnectOptions = {
   /** The account to connect to */
@@ -228,6 +238,10 @@ export class MetamaskConnectEVM {
     params: unknown[],
   ): Promise<void> {
     const coreOptions = this.#getCoreOptions();
+    if (!isAnalyticsEnabled(coreOptions)) {
+      return;
+    }
+
     try {
       const invokeOptions = this.#createInvokeOptions(method, scope, params);
       const props = await getWalletActionAnalyticsProperties(
@@ -255,6 +269,10 @@ export class MetamaskConnectEVM {
     params: unknown[],
   ): Promise<void> {
     const coreOptions = this.#getCoreOptions();
+    if (!isAnalyticsEnabled(coreOptions)) {
+      return;
+    }
+
     try {
       const invokeOptions = this.#createInvokeOptions(method, scope, params);
       const props = await getWalletActionAnalyticsProperties(
@@ -284,6 +302,10 @@ export class MetamaskConnectEVM {
     error: unknown,
   ): Promise<void> {
     const coreOptions = this.#getCoreOptions();
+    if (!isAnalyticsEnabled(coreOptions)) {
+      return;
+    }
+
     try {
       const invokeOptions = this.#createInvokeOptions(method, scope, params);
       const props = await getWalletActionAnalyticsProperties(
@@ -1008,6 +1030,7 @@ export class MetamaskConnectEVM {
  * @param options.dapp - Dapp identification and branding settings
  * @param options.api - API configuration including read-only RPC map
  * @param options.api.supportedNetworks - A map of hex chain IDs to RPC URLs for read-only requests
+ * @param [options.analytics.enabled] - Whether to enable dapp-side analytics (defaults to true)
  * @param [options.analytics.integrationType] - Integration type for analytics
  * @param [options.ui] - UI configuration options
  * @param [options.ui.headless] - Whether to run without UI
@@ -1071,6 +1094,7 @@ export async function createEVMClient(
         supportedNetworks: supportedNetworksCaipChainId,
       },
       analytics: {
+        ...(options.analytics ?? {}),
         // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
         integrationType: options.analytics?.integrationType || 'direct',
       },