feat: implement MM Connect Multichain Analytics (#46)

* feat: add connection analytics to connect-multichain

* feat: add request handling event tracking

* chore: update CHANGELOG.md

* feat: add wallet action event tracking for legacy EVM methods not passing through wallet_invokeMethod

* refactor: clean up event tracking logic

* chore: update CHANGELOG.md

* chore: update CHANGELOG.md

* refactor: minor removal of unreferenced methods

* refactor: update schema.ts properly after updating api specs and generating from metamask-sdk-analytics-api repo

* chore: update CHANGELOG.md

* chore: fix CHANGELOG.md

* chore: fix CHANGELOG.md

* test: misnamed property

* fix: change requestRouter to make sure readonly calls also call analytics

Author: ffmcgee725

packages/analytics/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added `v2/events/` endpoint to `schema.ts` ([#46](https://github.com/MetaMask/connect-monorepo/pull/46))
+
+### Changed
+
+- Updated `analytics.ts` to point towards `v2/events` endpoint and update payload accordingly ([#46](https://github.com/MetaMask/connect-monorepo/pull/46))
+
 ## [0.1.1]
 
 ### Added

packages/analytics/src/analytics.test.ts

@@ -6,13 +6,16 @@ import * as t from 'vitest';
 import Analytics from './analytics';
 import type * as schema from './schema';
 
+type EventV2 = schema.components['schemas']['EventV2'];
+type MMConnectPayload = schema.components['schemas']['MMConnectPayload'];
+type MMConnectProperties = schema.components['schemas']['MMConnectProperties'];
+
 t.describe('Analytics Integration', () => {
   let analytics: Analytics;
   let scope: nock.Scope;
 
-  const event: schema.components['schemas']['SdkInitializedEvent'] = {
-    name: 'sdk_initialized',
-    sdk_version: '1.0.0',
+  const eventProperties: MMConnectProperties = {
+    mmconnect_version: '1.0.0',
     dapp_id: 'aave.com',
     anon_id: 'bbbc1727-8b85-433a-a26a-e9df70ddc81c',
     platform: 'web-desktop',
@@ -25,9 +28,9 @@ t.describe('Analytics Integration', () => {
   });
 
   t.it('should do nothing when disabled', async () => {
-    let captured: Event[] = [];
+    let captured: EventV2[] = [];
     scope = nock('http://127.0.0.1')
-      .post('/v1/events', (body) => {
+      .post('/v2/events', (body) => {
         captured = body; // Capture the request body directly
         return true; // Accept any body to proceed with the intercept
       })
@@ -39,7 +42,7 @@ t.describe('Analytics Integration', () => {
       );
 
     analytics = new Analytics('http://127.0.0.1');
-    analytics.track(event.name, { ...event });
+    analytics.track('mmconnect_initialized', eventProperties);
 
     // Wait for the Sender to flush the event (baseIntervalMs = 200ms + buffer)
     await new Promise((resolve) => setTimeout(resolve, 300));
@@ -51,9 +54,9 @@ t.describe('Analytics Integration', () => {
   });
 
   t.it('should track an event when enabled', async () => {
-    let captured: Event[] = [];
+    let captured: EventV2[] = [];
     scope = nock('http://127.0.0.2')
-      .post('/v1/events', (body) => {
+      .post('/v2/events', (body) => {
         captured = body; // Capture the request body directly
         return true; // Accept any body to proceed with the intercept
       })
@@ -65,19 +68,33 @@ t.describe('Analytics Integration', () => {
 
     analytics = new Analytics('http://127.0.0.2');
     analytics.enable();
-    analytics.setGlobalProperty('sdk_version', event.sdk_version);
-    analytics.setGlobalProperty('anon_id', event.anon_id);
-    analytics.setGlobalProperty('platform', event.platform);
-    analytics.setGlobalProperty('integration_type', event.integration_type);
-    analytics.track(event.name, { dapp_id: 'some-non-global-property' });
+    analytics.setGlobalProperty(
+      'mmconnect_version',
+      eventProperties.mmconnect_version,
+    );
+    analytics.setGlobalProperty('anon_id', eventProperties.anon_id);
+    analytics.setGlobalProperty('platform', eventProperties.platform);
+    analytics.setGlobalProperty(
+      'integration_type',
+      eventProperties.integration_type,
+    );
+    analytics.track('mmconnect_initialized', {
+      dapp_id: 'dapp_id',
+    });
 
     // Wait for the Sender to flush the event (baseIntervalMs = 200ms + buffer)
     await new Promise((resolve) => setTimeout(resolve, 300));
 
     // Verify the captured payload
-    t.expect(captured).toEqual([
-      { ...event, dapp_id: 'some-non-global-property' },
-    ]);
+    const expectedEvent: MMConnectPayload = {
+      namespace: 'metamask/connect',
+      event_name: 'mmconnect_initialized',
+      properties: {
+        ...eventProperties,
+        dapp_id: 'dapp_id',
+      },
+    };
+    t.expect(captured).toEqual([expectedEvent]);
 
     scope.done();
   });

packages/analytics/src/analytics.ts

@@ -5,20 +5,23 @@ import createClient from 'openapi-fetch';
 import type * as schema from './schema';
 import Sender from './sender';
 
-type Event = schema.components['schemas']['Event'];
+type Event = schema.components['schemas']['EventV2'];
+type MMConnectPayload = schema.components['schemas']['MMConnectPayload'];
+type MMConnectProperties = schema.components['schemas']['MMConnectProperties'];
+type MMConnectEventName = MMConnectPayload['event_name'];
 
 class Analytics {
   private enabled = false;
 
   private readonly sender: Sender<Event>;
 
-  private properties: Record<string, string> = {};
+  private properties: Partial<MMConnectProperties> = {};
 
   constructor(baseUrl: string) {
     const client = createClient<schema.paths>({ baseUrl });
 
     const sendFn = async (batch: Event[]): Promise<void> => {
-      const res = await client.POST('/v1/events', { body: batch });
+      const res = await client.POST('/v2/events', { body: batch });
       if (res.response.status !== 200) {
         throw new Error(res.error);
       }
@@ -31,20 +34,26 @@ class Analytics {
     this.enabled = true;
   }
 
-  public setGlobalProperty(key: string, value: string): void {
+  public setGlobalProperty<K extends keyof MMConnectProperties>(
+    key: K,
+    value: MMConnectProperties[K],
+  ): void {
     this.properties[key] = value;
   }
 
-  public track<T extends Event>(name: T['name'], properties: Partial<T>): void {
+  public track(
+    eventName: MMConnectEventName,
+    properties: Partial<MMConnectProperties>,
+  ): void {
     if (!this.enabled) {
       return;
     }
 
-    const event = {
-      name,
-      ...this.properties,
-      ...properties,
-    } as T;
+    const event: MMConnectPayload = {
+      namespace: 'metamask/connect',
+      event_name: eventName,
+      properties: { ...properties, ...this.properties } as MMConnectProperties,
+    };
 
     this.sender.enqueue(event);
   }

packages/analytics/src/schema.ts

@@ -53,6 +53,55 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v2/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Track V2 namespaced events
+         * @description Endpoint to submit namespaced analytics events for the MetaMask SDK (version 2).
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["EventV2"][];
+                };
+            };
+            responses: {
+                /** @description Events tracked successfully */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @description Indicates the success of the event tracking.
+                             * @example success
+                             */
+                            status?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -421,6 +470,52 @@ export interface components {
              */
             platform: "extension" | "mobile";
         };
+        EventV2: components["schemas"]["MMConnectPayload"] | components["schemas"]["MobileSDKConnectV2Payload"];
+        MMConnectPayload: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            namespace: "metamask/connect";
+            /** @enum {string} */
+            event_name: "mmconnect_initialized" | "mmconnect_connection_initiated" | "mmconnect_connection_established" | "mmconnect_connection_rejected" | "mmconnect_connection_failed" | "mmconnect_wallet_action_requested" | "mmconnect_wallet_action_succeeded" | "mmconnect_wallet_action_failed" | "mmconnect_wallet_action_rejected";
+            properties: components["schemas"]["MMConnectProperties"];
+        };
+        MobileSDKConnectV2Payload: {
+            /**
+             * @description discriminator enum property added by openapi-typescript
+             * @enum {string}
+             */
+            namespace: "mobile/sdk-connect-v2";
+            /** @enum {string} */
+            event_name: "wallet_connection_request_received" | "wallet_connection_request_failed" | "wallet_connection_user_approved" | "wallet_connection_user_rejected" | "wallet_action_received" | "wallet_action_user_approved" | "wallet_action_user_rejected";
+            properties: components["schemas"]["MobileSDKConnectV2Properties"];
+        };
+        MMConnectProperties: {
+            mmconnect_version: string;
+            dapp_id: string;
+            /** Format: uuid */
+            anon_id: string;
+            /** @enum {string} */
+            platform: "web-desktop" | "web-mobile" | "nodejs" | "in-app-browser" | "react-native";
+            integration_type: string;
+            /** @enum {string} */
+            transport_type?: "browser" | "mwp" | "unknown";
+            method?: string;
+            caip_chain_id?: string;
+            /** @description Array of CAIP-2 chain IDs that the dApp has configured */
+            dapp_configured_chains?: string[];
+            /** @description Array of CAIP-2 chain IDs that the dApp has requested */
+            dapp_requested_chains?: string[];
+            /** @description Array of CAIP-2 chain IDs that the user has permissioned */
+            user_permissioned_chains?: string[];
+        };
+        MobileSDKConnectV2Properties: {
+            /** Format: uuid */
+            anon_id: string;
+            /** @enum {string} */
+            platform: "mobile";
+        };
     };
     responses: never;
     parameters: never;

packages/connect-evm/CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added analytics tracking of request handling ([#46](https://github.com/MetaMask/connect-monorepo/pull/46))
 - Initial release ([#21](https://github.com/MetaMask/connect-monorepo/pull/21))
 
 ### Fixed

packages/connect-evm/package.json

@@ -48,6 +48,7 @@
     "test:watch": "vitest watch"
   },
   "dependencies": {
+    "@metamask/analytics": "workspace:^",
     "@metamask/chain-agnostic-permission": "^1.2.2",
     "@metamask/connect-multichain": "workspace:^",
     "@metamask/utils": "^11.8.1"