@metamask-previews/analytics-controller 0.0.0-preview-de995bed → 0.0.0-preview-cb4a07d5

package/dist/AnalyticsController.cjs

@@ -10,12 +10,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _AnalyticsController_platformAdapter;
+var _AnalyticsController_platformAdapter, _AnalyticsController_isAnonymousEventsFeatureEnabled, _AnalyticsController_initialized;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsController = exports.getDefaultAnalyticsControllerState = exports.controllerName = void 0;
 const base_controller_1 = require("@metamask/base-controller");
-const uuid_1 = require("uuid");
+const analyticsControllerStateValidator_1 = require("./analyticsControllerStateValidator.cjs");
 const AnalyticsLogger_1 = require("./AnalyticsLogger.cjs");
+const selectors_1 = require("./selectors.cjs");
 // === GENERAL ===
 /**
  * The name of the {@link AnalyticsController}, used to namespace the
@@ -23,16 +24,29 @@ const AnalyticsLogger_1 = require("./AnalyticsLogger.cjs");
  * when composed with other controllers.
  */
 exports.controllerName = 'AnalyticsController';
+/**
+ * Returns default values for AnalyticsController state.
+ *
+ * Note: analyticsId is NOT included - it's an identity that must be
+ * provided by the platform (generated once on first run, then persisted).
+ *
+ * @returns Default state without analyticsId
+ */
+function getDefaultAnalyticsControllerState() {
+    return {
+        optedIn: false,
+    };
+}
+exports.getDefaultAnalyticsControllerState = getDefaultAnalyticsControllerState;
 /**
  * The metadata for each property in {@link AnalyticsControllerState}.
+ *
+ * Note: `optedIn` is persisted by the controller (`persist: true`).
+ * `analyticsId` is persisted by the platform (`persist: false`) and provided
+ * via initial state. The platform should subscribe to `stateChange` events
+ * to persist any state changes.
  */
 const analyticsControllerMetadata = {
-    enabled: {
-        includeInStateLogs: true,
-        persist: true,
-        includeInDebugSnapshot: true,
-        usedInUi: true,
-    },
     optedIn: {
         includeInStateLogs: true,
         persist: true,
@@ -41,34 +55,16 @@ const analyticsControllerMetadata = {
     },
     analyticsId: {
         includeInStateLogs: true,
-        persist: true,
+        persist: false,
         includeInDebugSnapshot: true,
         usedInUi: false,
     },
 };
-/**
- * Constructs the default {@link AnalyticsController} state. This allows
- * consumers to provide a partial state object when initializing the controller
- * and also helps in constructing complete state objects for this controller in
- * tests.
- *
- * @returns The default {@link AnalyticsController} state.
- */
-function getDefaultAnalyticsControllerState() {
-    return {
-        enabled: true,
-        optedIn: false,
-        analyticsId: (0, uuid_1.v4)(),
-    };
-}
-exports.getDefaultAnalyticsControllerState = getDefaultAnalyticsControllerState;
 // === MESSENGER ===
 const MESSENGER_EXPOSED_METHODS = [
     'trackEvent',
     'identify',
-    'trackPage',
-    'enable',
-    'disable',
+    'trackView',
     'optIn',
     'optOut',
 ];
@@ -81,100 +77,128 @@ const MESSENGER_EXPOSED_METHODS = [
  * This controller follows the MetaMask controller pattern and integrates with the
  * messenger system to allow other controllers and components to track analytics events.
  * It delegates platform-specific implementation to an {@link AnalyticsPlatformAdapter}.
+ *
+ * Note: The controller persists `optedIn` internally. The `analyticsId` is persisted
+ * by the platform and must be provided via initial state. The platform should subscribe
+ * to `AnalyticsController:stateChange` events to persist any state changes.
  */
 class AnalyticsController extends base_controller_1.BaseController {
     /**
      * Constructs an AnalyticsController instance.
      *
      * @param options - Controller options
-     * @param options.state - Initial controller state (defaults from getDefaultAnalyticsControllerState)
+     * @param options.state - Initial controller state. Must include a valid UUIDv4 `analyticsId`.
+     * Use `getDefaultAnalyticsControllerState()` for default opt-in preferences.
      * @param options.messenger - Messenger used to communicate with BaseController
      * @param options.platformAdapter - Platform adapter implementation for tracking
+     * @param options.isAnonymousEventsFeatureEnabled - Whether the anonymous events feature is enabled
+     * @throws Error if state.analyticsId is missing or not a valid UUIDv4
+     * @remarks After construction, call {@link AnalyticsController.init} to complete initialization.
      */
-    constructor({ state = {}, messenger, platformAdapter, }) {
+    constructor({ state, messenger, platformAdapter, isAnonymousEventsFeatureEnabled = false, }) {
+        const initialState = {
+            ...getDefaultAnalyticsControllerState(),
+            ...state,
+        };
+        (0, analyticsControllerStateValidator_1.validateAnalyticsControllerState)(initialState);
         super({
             name: exports.controllerName,
             metadata: analyticsControllerMetadata,
-            state: {
-                ...getDefaultAnalyticsControllerState(),
-                ...state,
-            },
+            state: initialState,
             messenger,
         });
         _AnalyticsController_platformAdapter.set(this, void 0);
+        _AnalyticsController_isAnonymousEventsFeatureEnabled.set(this, void 0);
+        _AnalyticsController_initialized.set(this, void 0);
+        __classPrivateFieldSet(this, _AnalyticsController_isAnonymousEventsFeatureEnabled, isAnonymousEventsFeatureEnabled, "f");
         __classPrivateFieldSet(this, _AnalyticsController_platformAdapter, platformAdapter, "f");
+        __classPrivateFieldSet(this, _AnalyticsController_initialized, false, "f");
         this.messenger.registerMethodActionHandlers(this, MESSENGER_EXPOSED_METHODS);
         (0, AnalyticsLogger_1.projectLogger)('AnalyticsController initialized and ready', {
-            enabled: this.state.enabled,
+            enabled: selectors_1.analyticsControllerSelectors.selectEnabled(this.state),
             optedIn: this.state.optedIn,
             analyticsId: this.state.analyticsId,
         });
     }
+    /**
+     * Initialize the controller by calling the platform adapter's onSetupCompleted lifecycle hook.
+     * This method must be called after construction to complete the setup process.
+     */
+    init() {
+        if (__classPrivateFieldGet(this, _AnalyticsController_initialized, "f")) {
+            (0, AnalyticsLogger_1.projectLogger)('AnalyticsController already initialized.');
+            return;
+        }
+        __classPrivateFieldSet(this, _AnalyticsController_initialized, true, "f");
+        // Call onSetupCompleted lifecycle hook after initialization
+        // State is already validated, so analyticsId is guaranteed to be a valid UUIDv4
+        try {
+            __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").onSetupCompleted(this.state.analyticsId);
+        }
+        catch (error) {
+            // Log error but don't throw - adapter setup failure shouldn't break controller
+            (0, AnalyticsLogger_1.projectLogger)('Error calling platformAdapter.onSetupCompleted', error);
+        }
+    }
     /**
      * Track an analytics event.
      *
      * Events are only tracked if analytics is enabled.
      *
-     * @param eventName - The name of the event
-     * @param properties - Event properties
+     * @param event - Analytics event with properties and sensitive properties
      */
-    trackEvent(eventName, properties = {}) {
+    trackEvent(event) {
         // Don't track if analytics is disabled
-        if (!this.state.enabled) {
+        if (!selectors_1.analyticsControllerSelectors.selectEnabled(this.state)) {
             return;
         }
-        // Delegate to platform adapter
-        __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").trackEvent(eventName, properties);
+        // if event does not have properties, send event without properties
+        // and return to prevent any additional processing
+        if (!event.hasProperties) {
+            __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").track(event.name);
+            return;
+        }
+        // Track regular properties first if anonymous events feature is enabled
+        if (__classPrivateFieldGet(this, _AnalyticsController_isAnonymousEventsFeatureEnabled, "f")) {
+            // Note: Even if regular properties object is empty, we still send it to ensure
+            // an event with user ID is tracked.
+            __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").track(event.name, {
+                ...event.properties,
+            });
+        }
+        const hasSensitiveProperties = Object.keys(event.sensitiveProperties).length > 0;
+        if (!__classPrivateFieldGet(this, _AnalyticsController_isAnonymousEventsFeatureEnabled, "f") || hasSensitiveProperties) {
+            __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").track(event.name, {
+                ...event.properties,
+                ...event.sensitiveProperties,
+                ...(hasSensitiveProperties && { anonymous: true }),
+            });
+        }
     }
     /**
      * Identify a user for analytics.
      *
-     * @param userId - The user identifier (e.g., metametrics ID)
      * @param traits - User traits/properties
      */
-    identify(userId, traits) {
-        if (!this.state.enabled) {
+    identify(traits) {
+        if (!selectors_1.analyticsControllerSelectors.selectEnabled(this.state)) {
             return;
         }
-        // Update state with analytics ID
-        this.update((state) => {
-            state.analyticsId = userId;
-        });
-        // Delegate to platform adapter if supported
-        if (__classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").identify) {
-            __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").identify(userId, traits);
-        }
+        // Delegate to platform adapter using the current analytics ID
+        __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").identify(this.state.analyticsId, traits);
     }
     /**
-     * Track a page view.
+     * Track a page or screen view.
      *
-     * @param pageName - The name of the page
-     * @param properties - Page properties
+     * @param name - The identifier/name of the page or screen being viewed (e.g., "home", "settings", "wallet")
+     * @param properties - Optional properties associated with the view
      */
-    trackPage(pageName, properties) {
-        if (!this.state.enabled) {
+    trackView(name, properties) {
+        if (!selectors_1.analyticsControllerSelectors.selectEnabled(this.state)) {
             return;
         }
-        // Delegate to platform adapter if supported
-        if (__classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").trackPage) {
-            __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").trackPage(pageName, properties);
-        }
-    }
-    /**
-     * Enable analytics tracking.
-     */
-    enable() {
-        this.update((state) => {
-            state.enabled = true;
-        });
-    }
-    /**
-     * Disable analytics tracking.
-     */
-    disable() {
-        this.update((state) => {
-            state.enabled = false;
-        });
+        // Delegate to platform adapter
+        __classPrivateFieldGet(this, _AnalyticsController_platformAdapter, "f").view(name, properties);
     }
     /**
      * Opt in to analytics.
@@ -194,5 +218,5 @@ class AnalyticsController extends base_controller_1.BaseController {
     }
 }
 exports.AnalyticsController = AnalyticsController;
-_AnalyticsController_platformAdapter = new WeakMap();
+_AnalyticsController_platformAdapter = new WeakMap(), _AnalyticsController_isAnonymousEventsFeatureEnabled = new WeakMap(), _AnalyticsController_initialized = new WeakMap();
 //# sourceMappingURL=AnalyticsController.cjs.map

package/dist/AnalyticsController.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsController.cjs","sourceRoot":"","sources":["../src/AnalyticsController.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\nimport { v4 as uuidv4 } from 'uuid';\n\nimport type { AnalyticsControllerMethodActions } from './AnalyticsController-method-action-types';\nimport { projectLogger } from './AnalyticsLogger';\nimport type {\n  AnalyticsPlatformAdapter,\n  AnalyticsEventProperties,\n} from './AnalyticsPlatformAdapter.types';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link AnalyticsController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'AnalyticsController';\n\n// === STATE ===\n\n/**\n * Describes the shape of the state object for {@link AnalyticsController}.\n */\nexport type AnalyticsControllerState = {\n  /**\n   * Whether analytics tracking is enabled\n   */\n  enabled: boolean;\n\n  /**\n   * Whether the user has opted in to analytics\n   */\n  optedIn: boolean;\n\n  /**\n   * User's UUIDv4 analytics identifier\n   */\n  analyticsId: string;\n};\n\n/**\n * The metadata for each property in {@link AnalyticsControllerState}.\n */\nconst analyticsControllerMetadata = {\n  enabled: {\n    includeInStateLogs: true,\n    persist: true,\n    includeInDebugSnapshot: true,\n    usedInUi: true,\n  },\n  optedIn: {\n    includeInStateLogs: true,\n    persist: true,\n    includeInDebugSnapshot: true,\n    usedInUi: true,\n  },\n  analyticsId: {\n    includeInStateLogs: true,\n    persist: true,\n    includeInDebugSnapshot: true,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<AnalyticsControllerState>;\n\n/**\n * Constructs the default {@link AnalyticsController} state. This allows\n * consumers to provide a partial state object when initializing the controller\n * and also helps in constructing complete state objects for this controller in\n * tests.\n *\n * @returns The default {@link AnalyticsController} state.\n */\nexport function getDefaultAnalyticsControllerState(): AnalyticsControllerState {\n  return {\n    enabled: true,\n    optedIn: false,\n    analyticsId: uuidv4(),\n  };\n}\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'trackEvent',\n  'identify',\n  'trackPage',\n  'enable',\n  'disable',\n  'optIn',\n  'optOut',\n] as const;\n\n/**\n * Returns the state of the {@link AnalyticsController}.\n */\nexport type AnalyticsControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  AnalyticsControllerState\n>;\n\n/**\n * Actions that {@link AnalyticsControllerMessenger} exposes to other consumers.\n */\nexport type AnalyticsControllerActions =\n  | AnalyticsControllerGetStateAction\n  | AnalyticsControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link AnalyticsControllerMessenger} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Event emitted when the state of the {@link AnalyticsController} changes.\n */\nexport type AnalyticsControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  AnalyticsControllerState\n>;\n\n/**\n * Events that {@link AnalyticsControllerMessenger} exposes to other consumers.\n */\nexport type AnalyticsControllerEvents = AnalyticsControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link AnalyticsControllerMessenger} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link AnalyticsController}.\n */\nexport type AnalyticsControllerMessenger = Messenger<\n  typeof controllerName,\n  AnalyticsControllerActions | AllowedActions,\n  AnalyticsControllerEvents | AllowedEvents\n>;\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * The options that AnalyticsController takes.\n */\nexport type AnalyticsControllerOptions = {\n  state?: Partial<AnalyticsControllerState>;\n  messenger: AnalyticsControllerMessenger;\n  /**\n   * Platform adapter implementation for tracking events\n   */\n  platformAdapter: AnalyticsPlatformAdapter;\n};\n\n/**\n * The AnalyticsController manages analytics tracking across platforms (Mobile/Extension).\n * It provides a unified interface for tracking events, identifying users, and managing\n * analytics preferences while delegating platform-specific implementation to an\n * {@link AnalyticsPlatformAdapter}.\n *\n * This controller follows the MetaMask controller pattern and integrates with the\n * messenger system to allow other controllers and components to track analytics events.\n * It delegates platform-specific implementation to an {@link AnalyticsPlatformAdapter}.\n */\nexport class AnalyticsController extends BaseController<\n  'AnalyticsController',\n  AnalyticsControllerState,\n  AnalyticsControllerMessenger\n> {\n  readonly #platformAdapter: AnalyticsPlatformAdapter;\n\n  /**\n   * Constructs an AnalyticsController instance.\n   *\n   * @param options - Controller options\n   * @param options.state - Initial controller state (defaults from getDefaultAnalyticsControllerState)\n   * @param options.messenger - Messenger used to communicate with BaseController\n   * @param options.platformAdapter - Platform adapter implementation for tracking\n   */\n  constructor({\n    state = {},\n    messenger,\n    platformAdapter,\n  }: AnalyticsControllerOptions) {\n    super({\n      name: controllerName,\n      metadata: analyticsControllerMetadata,\n      state: {\n        ...getDefaultAnalyticsControllerState(),\n        ...state,\n      },\n      messenger,\n    });\n\n    this.#platformAdapter = platformAdapter;\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n\n    projectLogger('AnalyticsController initialized and ready', {\n      enabled: this.state.enabled,\n      optedIn: this.state.optedIn,\n      analyticsId: this.state.analyticsId,\n    });\n  }\n\n  /**\n   * Track an analytics event.\n   *\n   * Events are only tracked if analytics is enabled.\n   *\n   * @param eventName - The name of the event\n   * @param properties - Event properties\n   */\n  trackEvent(\n    eventName: string,\n    properties: AnalyticsEventProperties = {},\n  ): void {\n    // Don't track if analytics is disabled\n    if (!this.state.enabled) {\n      return;\n    }\n\n    // Delegate to platform adapter\n    this.#platformAdapter.trackEvent(eventName, properties);\n  }\n\n  /**\n   * Identify a user for analytics.\n   *\n   * @param userId - The user identifier (e.g., metametrics ID)\n   * @param traits - User traits/properties\n   */\n  identify(userId: string, traits?: AnalyticsEventProperties): void {\n    if (!this.state.enabled) {\n      return;\n    }\n\n    // Update state with analytics ID\n    this.update((state) => {\n      state.analyticsId = userId;\n    });\n\n    // Delegate to platform adapter if supported\n    if (this.#platformAdapter.identify) {\n      this.#platformAdapter.identify(userId, traits);\n    }\n  }\n\n  /**\n   * Track a page view.\n   *\n   * @param pageName - The name of the page\n   * @param properties - Page properties\n   */\n  trackPage(pageName: string, properties?: AnalyticsEventProperties): void {\n    if (!this.state.enabled) {\n      return;\n    }\n\n    // Delegate to platform adapter if supported\n    if (this.#platformAdapter.trackPage) {\n      this.#platformAdapter.trackPage(pageName, properties);\n    }\n  }\n\n  /**\n   * Enable analytics tracking.\n   */\n  enable(): void {\n    this.update((state) => {\n      state.enabled = true;\n    });\n  }\n\n  /**\n   * Disable analytics tracking.\n   */\n  disable(): void {\n    this.update((state) => {\n      state.enabled = false;\n    });\n  }\n\n  /**\n   * Opt in to analytics.\n   */\n  optIn(): void {\n    this.update((state) => {\n      state.optedIn = true;\n    });\n  }\n\n  /**\n   * Opt out of analytics.\n   */\n  optOut(): void {\n    this.update((state) => {\n      state.optedIn = false;\n    });\n  }\n}\n"]}
+{"version":3,"file":"AnalyticsController.cjs","sourceRoot":"","sources":["../src/AnalyticsController.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  ControllerGetStateAction,\n  ControllerStateChangeEvent,\n  StateMetadata,\n} from '@metamask/base-controller';\nimport { BaseController } from '@metamask/base-controller';\nimport type { Messenger } from '@metamask/messenger';\n\nimport type { AnalyticsControllerMethodActions } from './AnalyticsController-method-action-types';\nimport { validateAnalyticsControllerState } from './analyticsControllerStateValidator';\nimport { projectLogger as log } from './AnalyticsLogger';\nimport type {\n  AnalyticsPlatformAdapter,\n  AnalyticsEventProperties,\n  AnalyticsUserTraits,\n  AnalyticsTrackingEvent,\n} from './AnalyticsPlatformAdapter.types';\nimport { analyticsControllerSelectors } from './selectors';\n\n// === GENERAL ===\n\n/**\n * The name of the {@link AnalyticsController}, used to namespace the\n * controller's actions and events and to namespace the controller's state data\n * when composed with other controllers.\n */\nexport const controllerName = 'AnalyticsController';\n\n// === STATE ===\n\n/**\n * Describes the shape of the state object for {@link AnalyticsController}.\n */\nexport type AnalyticsControllerState = {\n  /**\n   * Whether the user has opted in to analytics.\n   */\n  optedIn: boolean;\n\n  /**\n   * User's UUIDv4 analytics identifier.\n   * This is an identity (unique per user), not a preference.\n   * Must be provided by the platform - the controller does not generate it.\n   */\n  analyticsId: string;\n};\n\n/**\n * Returns default values for AnalyticsController state.\n *\n * Note: analyticsId is NOT included - it's an identity that must be\n * provided by the platform (generated once on first run, then persisted).\n *\n * @returns Default state without analyticsId\n */\nexport function getDefaultAnalyticsControllerState(): Omit<\n  AnalyticsControllerState,\n  'analyticsId'\n> {\n  return {\n    optedIn: false,\n  };\n}\n\n/**\n * The metadata for each property in {@link AnalyticsControllerState}.\n *\n * Note: `optedIn` is persisted by the controller (`persist: true`).\n * `analyticsId` is persisted by the platform (`persist: false`) and provided\n * via initial state. The platform should subscribe to `stateChange` events\n * to persist any state changes.\n */\nconst analyticsControllerMetadata = {\n  optedIn: {\n    includeInStateLogs: true,\n    persist: true,\n    includeInDebugSnapshot: true,\n    usedInUi: true,\n  },\n  analyticsId: {\n    includeInStateLogs: true,\n    persist: false,\n    includeInDebugSnapshot: true,\n    usedInUi: false,\n  },\n} satisfies StateMetadata<AnalyticsControllerState>;\n\n// === MESSENGER ===\n\nconst MESSENGER_EXPOSED_METHODS = [\n  'trackEvent',\n  'identify',\n  'trackView',\n  'optIn',\n  'optOut',\n] as const;\n\n/**\n * Returns the state of the {@link AnalyticsController}.\n */\nexport type AnalyticsControllerGetStateAction = ControllerGetStateAction<\n  typeof controllerName,\n  AnalyticsControllerState\n>;\n\n/**\n * Actions that {@link AnalyticsControllerMessenger} exposes to other consumers.\n */\nexport type AnalyticsControllerActions =\n  | AnalyticsControllerGetStateAction\n  | AnalyticsControllerMethodActions;\n\n/**\n * Actions from other messengers that {@link AnalyticsControllerMessenger} calls.\n */\ntype AllowedActions = never;\n\n/**\n * Event emitted when the state of the {@link AnalyticsController} changes.\n */\nexport type AnalyticsControllerStateChangeEvent = ControllerStateChangeEvent<\n  typeof controllerName,\n  AnalyticsControllerState\n>;\n\n/**\n * Events that {@link AnalyticsControllerMessenger} exposes to other consumers.\n */\nexport type AnalyticsControllerEvents = AnalyticsControllerStateChangeEvent;\n\n/**\n * Events from other messengers that {@link AnalyticsControllerMessenger} subscribes to.\n */\ntype AllowedEvents = never;\n\n/**\n * The messenger restricted to actions and events accessed by\n * {@link AnalyticsController}.\n */\nexport type AnalyticsControllerMessenger = Messenger<\n  typeof controllerName,\n  AnalyticsControllerActions | AllowedActions,\n  AnalyticsControllerEvents | AllowedEvents\n>;\n\n// === CONTROLLER DEFINITION ===\n\n/**\n * The options that AnalyticsController takes.\n */\nexport type AnalyticsControllerOptions = {\n  /**\n   * Initial controller state. Must include a valid UUIDv4 `analyticsId`.\n   * The platform is responsible for generating and persisting the analyticsId.\n   */\n  state: AnalyticsControllerState;\n  /**\n   * Messenger used to communicate with BaseController and other controllers.\n   */\n  messenger: AnalyticsControllerMessenger;\n  /**\n   * Platform adapter implementation for tracking events.\n   */\n  platformAdapter: AnalyticsPlatformAdapter;\n\n  /**\n   * Whether the anonymous events feature is enabled.\n   *\n   * @default false\n   */\n  isAnonymousEventsFeatureEnabled?: boolean;\n};\n\n/**\n * The AnalyticsController manages analytics tracking across platforms (Mobile/Extension).\n * It provides a unified interface for tracking events, identifying users, and managing\n * analytics preferences while delegating platform-specific implementation to an\n * {@link AnalyticsPlatformAdapter}.\n *\n * This controller follows the MetaMask controller pattern and integrates with the\n * messenger system to allow other controllers and components to track analytics events.\n * It delegates platform-specific implementation to an {@link AnalyticsPlatformAdapter}.\n *\n * Note: The controller persists `optedIn` internally. The `analyticsId` is persisted\n * by the platform and must be provided via initial state. The platform should subscribe\n * to `AnalyticsController:stateChange` events to persist any state changes.\n */\nexport class AnalyticsController extends BaseController<\n  'AnalyticsController',\n  AnalyticsControllerState,\n  AnalyticsControllerMessenger\n> {\n  readonly #platformAdapter: AnalyticsPlatformAdapter;\n\n  readonly #isAnonymousEventsFeatureEnabled: boolean;\n\n  #initialized: boolean;\n\n  /**\n   * Constructs an AnalyticsController instance.\n   *\n   * @param options - Controller options\n   * @param options.state - Initial controller state. Must include a valid UUIDv4 `analyticsId`.\n   * Use `getDefaultAnalyticsControllerState()` for default opt-in preferences.\n   * @param options.messenger - Messenger used to communicate with BaseController\n   * @param options.platformAdapter - Platform adapter implementation for tracking\n   * @param options.isAnonymousEventsFeatureEnabled - Whether the anonymous events feature is enabled\n   * @throws Error if state.analyticsId is missing or not a valid UUIDv4\n   * @remarks After construction, call {@link AnalyticsController.init} to complete initialization.\n   */\n  constructor({\n    state,\n    messenger,\n    platformAdapter,\n    isAnonymousEventsFeatureEnabled = false,\n  }: AnalyticsControllerOptions) {\n    const initialState: AnalyticsControllerState = {\n      ...getDefaultAnalyticsControllerState(),\n      ...state,\n    };\n\n    validateAnalyticsControllerState(initialState);\n\n    super({\n      name: controllerName,\n      metadata: analyticsControllerMetadata,\n      state: initialState,\n      messenger,\n    });\n\n    this.#isAnonymousEventsFeatureEnabled = isAnonymousEventsFeatureEnabled;\n    this.#platformAdapter = platformAdapter;\n    this.#initialized = false;\n\n    this.messenger.registerMethodActionHandlers(\n      this,\n      MESSENGER_EXPOSED_METHODS,\n    );\n\n    log('AnalyticsController initialized and ready', {\n      enabled: analyticsControllerSelectors.selectEnabled(this.state),\n      optedIn: this.state.optedIn,\n      analyticsId: this.state.analyticsId,\n    });\n  }\n\n  /**\n   * Initialize the controller by calling the platform adapter's onSetupCompleted lifecycle hook.\n   * This method must be called after construction to complete the setup process.\n   */\n  init(): void {\n    if (this.#initialized) {\n      log('AnalyticsController already initialized.');\n      return;\n    }\n\n    this.#initialized = true;\n\n    // Call onSetupCompleted lifecycle hook after initialization\n    // State is already validated, so analyticsId is guaranteed to be a valid UUIDv4\n    try {\n      this.#platformAdapter.onSetupCompleted(this.state.analyticsId);\n    } catch (error) {\n      // Log error but don't throw - adapter setup failure shouldn't break controller\n      log('Error calling platformAdapter.onSetupCompleted', error);\n    }\n  }\n\n  /**\n   * Track an analytics event.\n   *\n   * Events are only tracked if analytics is enabled.\n   *\n   * @param event - Analytics event with properties and sensitive properties\n   */\n  trackEvent(event: AnalyticsTrackingEvent): void {\n    // Don't track if analytics is disabled\n    if (!analyticsControllerSelectors.selectEnabled(this.state)) {\n      return;\n    }\n\n    // if event does not have properties, send event without properties\n    // and return to prevent any additional processing\n    if (!event.hasProperties) {\n      this.#platformAdapter.track(event.name);\n      return;\n    }\n\n    // Track regular properties first if anonymous events feature is enabled\n    if (this.#isAnonymousEventsFeatureEnabled) {\n      // Note: Even if regular properties object is empty, we still send it to ensure\n      // an event with user ID is tracked.\n      this.#platformAdapter.track(event.name, {\n        ...event.properties,\n      });\n    }\n\n    const hasSensitiveProperties =\n      Object.keys(event.sensitiveProperties).length > 0;\n\n    if (!this.#isAnonymousEventsFeatureEnabled || hasSensitiveProperties) {\n      this.#platformAdapter.track(event.name, {\n        ...event.properties,\n        ...event.sensitiveProperties,\n        ...(hasSensitiveProperties && { anonymous: true }),\n      });\n    }\n  }\n\n  /**\n   * Identify a user for analytics.\n   *\n   * @param traits - User traits/properties\n   */\n  identify(traits?: AnalyticsUserTraits): void {\n    if (!analyticsControllerSelectors.selectEnabled(this.state)) {\n      return;\n    }\n\n    // Delegate to platform adapter using the current analytics ID\n    this.#platformAdapter.identify(this.state.analyticsId, traits);\n  }\n\n  /**\n   * Track a page or screen view.\n   *\n   * @param name - The identifier/name of the page or screen being viewed (e.g., \"home\", \"settings\", \"wallet\")\n   * @param properties - Optional properties associated with the view\n   */\n  trackView(name: string, properties?: AnalyticsEventProperties): void {\n    if (!analyticsControllerSelectors.selectEnabled(this.state)) {\n      return;\n    }\n\n    // Delegate to platform adapter\n    this.#platformAdapter.view(name, properties);\n  }\n\n  /**\n   * Opt in to analytics.\n   */\n  optIn(): void {\n    this.update((state) => {\n      state.optedIn = true;\n    });\n  }\n\n  /**\n   * Opt out of analytics.\n   */\n  optOut(): void {\n    this.update((state) => {\n      state.optedIn = false;\n    });\n  }\n}\n"]}

package/dist/AnalyticsController.d.cts

@@ -2,7 +2,7 @@ import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@meta
 import { BaseController } from "@metamask/base-controller";
 import type { Messenger } from "@metamask/messenger";
 import type { AnalyticsControllerMethodActions } from "./AnalyticsController-method-action-types.cjs";
-import type { AnalyticsPlatformAdapter, AnalyticsEventProperties } from "./AnalyticsPlatformAdapter.types.cjs";
+import type { AnalyticsPlatformAdapter, AnalyticsEventProperties, AnalyticsUserTraits, AnalyticsTrackingEvent } from "./AnalyticsPlatformAdapter.types.cjs";
 /**
  * The name of the {@link AnalyticsController}, used to namespace the
  * controller's actions and events and to namespace the controller's state data
@@ -14,27 +14,25 @@ export declare const controllerName = "AnalyticsController";
  */
 export type AnalyticsControllerState = {
     /**
-     * Whether analytics tracking is enabled
-     */
-    enabled: boolean;
-    /**
-     * Whether the user has opted in to analytics
+     * Whether the user has opted in to analytics.
      */
     optedIn: boolean;
     /**
-     * User's UUIDv4 analytics identifier
+     * User's UUIDv4 analytics identifier.
+     * This is an identity (unique per user), not a preference.
+     * Must be provided by the platform - the controller does not generate it.
      */
     analyticsId: string;
 };
 /**
- * Constructs the default {@link AnalyticsController} state. This allows
- * consumers to provide a partial state object when initializing the controller
- * and also helps in constructing complete state objects for this controller in
- * tests.
+ * Returns default values for AnalyticsController state.
+ *
+ * Note: analyticsId is NOT included - it's an identity that must be
+ * provided by the platform (generated once on first run, then persisted).
  *
- * @returns The default {@link AnalyticsController} state.
+ * @returns Default state without analyticsId
  */
-export declare function getDefaultAnalyticsControllerState(): AnalyticsControllerState;
+export declare function getDefaultAnalyticsControllerState(): Omit<AnalyticsControllerState, 'analyticsId'>;
 /**
  * Returns the state of the {@link AnalyticsController}.
  */
@@ -68,12 +66,25 @@ export type AnalyticsControllerMessenger = Messenger<typeof controllerName, Anal
  * The options that AnalyticsController takes.
  */
 export type AnalyticsControllerOptions = {
-    state?: Partial<AnalyticsControllerState>;
+    /**
+     * Initial controller state. Must include a valid UUIDv4 `analyticsId`.
+     * The platform is responsible for generating and persisting the analyticsId.
+     */
+    state: AnalyticsControllerState;
+    /**
+     * Messenger used to communicate with BaseController and other controllers.
+     */
     messenger: AnalyticsControllerMessenger;
     /**
-     * Platform adapter implementation for tracking events
+     * Platform adapter implementation for tracking events.
      */
     platformAdapter: AnalyticsPlatformAdapter;
+    /**
+     * Whether the anonymous events feature is enabled.
+     *
+     * @default false
+     */
+    isAnonymousEventsFeatureEnabled?: boolean;
 };
 /**
  * The AnalyticsController manages analytics tracking across platforms (Mobile/Extension).
@@ -84,6 +95,10 @@ export type AnalyticsControllerOptions = {
  * This controller follows the MetaMask controller pattern and integrates with the
  * messenger system to allow other controllers and components to track analytics events.
  * It delegates platform-specific implementation to an {@link AnalyticsPlatformAdapter}.
+ *
+ * Note: The controller persists `optedIn` internally. The `analyticsId` is persisted
+ * by the platform and must be provided via initial state. The platform should subscribe
+ * to `AnalyticsController:stateChange` events to persist any state changes.
  */
 export declare class AnalyticsController extends BaseController<'AnalyticsController', AnalyticsControllerState, AnalyticsControllerMessenger> {
     #private;
@@ -91,42 +106,41 @@ export declare class AnalyticsController extends BaseController<'AnalyticsContro
      * Constructs an AnalyticsController instance.
      *
      * @param options - Controller options
-     * @param options.state - Initial controller state (defaults from getDefaultAnalyticsControllerState)
+     * @param options.state - Initial controller state. Must include a valid UUIDv4 `analyticsId`.
+     * Use `getDefaultAnalyticsControllerState()` for default opt-in preferences.
      * @param options.messenger - Messenger used to communicate with BaseController
      * @param options.platformAdapter - Platform adapter implementation for tracking
+     * @param options.isAnonymousEventsFeatureEnabled - Whether the anonymous events feature is enabled
+     * @throws Error if state.analyticsId is missing or not a valid UUIDv4
+     * @remarks After construction, call {@link AnalyticsController.init} to complete initialization.
+     */
+    constructor({ state, messenger, platformAdapter, isAnonymousEventsFeatureEnabled, }: AnalyticsControllerOptions);
+    /**
+     * Initialize the controller by calling the platform adapter's onSetupCompleted lifecycle hook.
+     * This method must be called after construction to complete the setup process.
      */
-    constructor({ state, messenger, platformAdapter, }: AnalyticsControllerOptions);
+    init(): void;
     /**
      * Track an analytics event.
      *
      * Events are only tracked if analytics is enabled.
      *
-     * @param eventName - The name of the event
-     * @param properties - Event properties
+     * @param event - Analytics event with properties and sensitive properties
      */
-    trackEvent(eventName: string, properties?: AnalyticsEventProperties): void;
+    trackEvent(event: AnalyticsTrackingEvent): void;
     /**
      * Identify a user for analytics.
      *
-     * @param userId - The user identifier (e.g., metametrics ID)
      * @param traits - User traits/properties
      */
-    identify(userId: string, traits?: AnalyticsEventProperties): void;
+    identify(traits?: AnalyticsUserTraits): void;
     /**
-     * Track a page view.
+     * Track a page or screen view.
      *
-     * @param pageName - The name of the page
-     * @param properties - Page properties
-     */
-    trackPage(pageName: string, properties?: AnalyticsEventProperties): void;
-    /**
-     * Enable analytics tracking.
-     */
-    enable(): void;
-    /**
-     * Disable analytics tracking.
+     * @param name - The identifier/name of the page or screen being viewed (e.g., "home", "settings", "wallet")
+     * @param properties - Optional properties associated with the view
      */
-    disable(): void;
+    trackView(name: string, properties?: AnalyticsEventProperties): void;
     /**
      * Opt in to analytics.
      */

package/dist/AnalyticsController.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"AnalyticsController.d.cts","sourceRoot":"","sources":["../src/AnalyticsController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAGrD,OAAO,KAAK,EAAE,gCAAgC,EAAE,sDAAkD;AAElG,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACzB,6CAAyC;AAI1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAIpD;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AA0BF;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,IAAI,wBAAwB,CAM7E;AAcD;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG,wBAAwB,CACtE,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,iCAAiC,GACjC,gCAAgC,CAAC;AAErC;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,0BAA0B,CAC1E,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,mCAAmC,CAAC;AAE5E;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,CAClD,OAAO,cAAc,EACrB,0BAA0B,GAAG,cAAc,EAC3C,yBAAyB,GAAG,aAAa,CAC1C,CAAC;AAIF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,KAAK,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAC1C,SAAS,EAAE,4BAA4B,CAAC;IACxC;;OAEG;IACH,eAAe,EAAE,wBAAwB,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,SAAQ,cAAc,CACrD,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,CAC7B;;IAGC;;;;;;;OAOG;gBACS,EACV,KAAU,EACV,SAAS,EACT,eAAe,GAChB,EAAE,0BAA0B;IAyB7B;;;;;;;OAOG;IACH,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,wBAA6B,GACxC,IAAI;IAUP;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAgBjE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,wBAAwB,GAAG,IAAI;IAWxE;;OAEG;IACH,MAAM,IAAI,IAAI;IAMd;;OAEG;IACH,OAAO,IAAI,IAAI;IAMf;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,MAAM,IAAI,IAAI;CAKf"}
+{"version":3,"file":"AnalyticsController.d.cts","sourceRoot":"","sources":["../src/AnalyticsController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAE3B,kCAAkC;AACnC,OAAO,EAAE,cAAc,EAAE,kCAAkC;AAC3D,OAAO,KAAK,EAAE,SAAS,EAAE,4BAA4B;AAErD,OAAO,KAAK,EAAE,gCAAgC,EAAE,sDAAkD;AAGlG,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACvB,6CAAyC;AAK1C;;;;GAIG;AACH,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAIpD;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kCAAkC,IAAI,IAAI,CACxD,wBAAwB,EACxB,aAAa,CACd,CAIA;AAmCD;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG,wBAAwB,CACtE,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,iCAAiC,GACjC,gCAAgC,CAAC;AAErC;;GAEG;AACH,KAAK,cAAc,GAAG,KAAK,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,mCAAmC,GAAG,0BAA0B,CAC1E,OAAO,cAAc,EACrB,wBAAwB,CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,yBAAyB,GAAG,mCAAmC,CAAC;AAE5E;;GAEG;AACH,KAAK,aAAa,GAAG,KAAK,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,CAClD,OAAO,cAAc,EACrB,0BAA0B,GAAG,cAAc,EAC3C,yBAAyB,GAAG,aAAa,CAC1C,CAAC;AAIF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC;;;OAGG;IACH,KAAK,EAAE,wBAAwB,CAAC;IAChC;;OAEG;IACH,SAAS,EAAE,4BAA4B,CAAC;IACxC;;OAEG;IACH,eAAe,EAAE,wBAAwB,CAAC;IAE1C;;;;OAIG;IACH,+BAA+B,CAAC,EAAE,OAAO,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAoB,SAAQ,cAAc,CACrD,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,CAC7B;;IAOC;;;;;;;;;;;OAWG;gBACS,EACV,KAAK,EACL,SAAS,EACT,eAAe,EACf,+BAAuC,GACxC,EAAE,0BAA0B;IA+B7B;;;OAGG;IACH,IAAI,IAAI,IAAI;IAkBZ;;;;;;OAMG;IACH,UAAU,CAAC,KAAK,EAAE,sBAAsB,GAAG,IAAI;IAkC/C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI;IAS5C;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,wBAAwB,GAAG,IAAI;IASpE;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,MAAM,IAAI,IAAI;CAKf"}

package/dist/AnalyticsController.d.mts

@@ -2,7 +2,7 @@ import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@meta
 import { BaseController } from "@metamask/base-controller";
 import type { Messenger } from "@metamask/messenger";
 import type { AnalyticsControllerMethodActions } from "./AnalyticsController-method-action-types.mjs";
-import type { AnalyticsPlatformAdapter, AnalyticsEventProperties } from "./AnalyticsPlatformAdapter.types.mjs";
+import type { AnalyticsPlatformAdapter, AnalyticsEventProperties, AnalyticsUserTraits, AnalyticsTrackingEvent } from "./AnalyticsPlatformAdapter.types.mjs";
 /**
  * The name of the {@link AnalyticsController}, used to namespace the
  * controller's actions and events and to namespace the controller's state data
@@ -14,27 +14,25 @@ export declare const controllerName = "AnalyticsController";
  */
 export type AnalyticsControllerState = {
     /**
-     * Whether analytics tracking is enabled
-     */
-    enabled: boolean;
-    /**
-     * Whether the user has opted in to analytics
+     * Whether the user has opted in to analytics.
      */
     optedIn: boolean;
     /**
-     * User's UUIDv4 analytics identifier
+     * User's UUIDv4 analytics identifier.
+     * This is an identity (unique per user), not a preference.
+     * Must be provided by the platform - the controller does not generate it.
      */
     analyticsId: string;
 };
 /**
- * Constructs the default {@link AnalyticsController} state. This allows
- * consumers to provide a partial state object when initializing the controller
- * and also helps in constructing complete state objects for this controller in
- * tests.
+ * Returns default values for AnalyticsController state.
+ *
+ * Note: analyticsId is NOT included - it's an identity that must be
+ * provided by the platform (generated once on first run, then persisted).
  *
- * @returns The default {@link AnalyticsController} state.
+ * @returns Default state without analyticsId
  */
-export declare function getDefaultAnalyticsControllerState(): AnalyticsControllerState;
+export declare function getDefaultAnalyticsControllerState(): Omit<AnalyticsControllerState, 'analyticsId'>;
 /**
  * Returns the state of the {@link AnalyticsController}.
  */
@@ -68,12 +66,25 @@ export type AnalyticsControllerMessenger = Messenger<typeof controllerName, Anal
  * The options that AnalyticsController takes.
  */
 export type AnalyticsControllerOptions = {
-    state?: Partial<AnalyticsControllerState>;
+    /**
+     * Initial controller state. Must include a valid UUIDv4 `analyticsId`.
+     * The platform is responsible for generating and persisting the analyticsId.
+     */
+    state: AnalyticsControllerState;
+    /**
+     * Messenger used to communicate with BaseController and other controllers.
+     */
     messenger: AnalyticsControllerMessenger;
     /**
-     * Platform adapter implementation for tracking events
+     * Platform adapter implementation for tracking events.
      */
     platformAdapter: AnalyticsPlatformAdapter;
+    /**
+     * Whether the anonymous events feature is enabled.
+     *
+     * @default false
+     */
+    isAnonymousEventsFeatureEnabled?: boolean;
 };
 /**
  * The AnalyticsController manages analytics tracking across platforms (Mobile/Extension).
@@ -84,6 +95,10 @@ export type AnalyticsControllerOptions = {
  * This controller follows the MetaMask controller pattern and integrates with the
  * messenger system to allow other controllers and components to track analytics events.
  * It delegates platform-specific implementation to an {@link AnalyticsPlatformAdapter}.
+ *
+ * Note: The controller persists `optedIn` internally. The `analyticsId` is persisted
+ * by the platform and must be provided via initial state. The platform should subscribe
+ * to `AnalyticsController:stateChange` events to persist any state changes.
  */
 export declare class AnalyticsController extends BaseController<'AnalyticsController', AnalyticsControllerState, AnalyticsControllerMessenger> {
     #private;
@@ -91,42 +106,41 @@ export declare class AnalyticsController extends BaseController<'AnalyticsContro
      * Constructs an AnalyticsController instance.
      *
      * @param options - Controller options
-     * @param options.state - Initial controller state (defaults from getDefaultAnalyticsControllerState)
+     * @param options.state - Initial controller state. Must include a valid UUIDv4 `analyticsId`.
+     * Use `getDefaultAnalyticsControllerState()` for default opt-in preferences.
      * @param options.messenger - Messenger used to communicate with BaseController
      * @param options.platformAdapter - Platform adapter implementation for tracking
+     * @param options.isAnonymousEventsFeatureEnabled - Whether the anonymous events feature is enabled
+     * @throws Error if state.analyticsId is missing or not a valid UUIDv4
+     * @remarks After construction, call {@link AnalyticsController.init} to complete initialization.
+     */
+    constructor({ state, messenger, platformAdapter, isAnonymousEventsFeatureEnabled, }: AnalyticsControllerOptions);
+    /**
+     * Initialize the controller by calling the platform adapter's onSetupCompleted lifecycle hook.
+     * This method must be called after construction to complete the setup process.
      */
-    constructor({ state, messenger, platformAdapter, }: AnalyticsControllerOptions);
+    init(): void;
     /**
      * Track an analytics event.
      *
      * Events are only tracked if analytics is enabled.
      *
-     * @param eventName - The name of the event
-     * @param properties - Event properties
+     * @param event - Analytics event with properties and sensitive properties
      */
-    trackEvent(eventName: string, properties?: AnalyticsEventProperties): void;
+    trackEvent(event: AnalyticsTrackingEvent): void;
     /**
      * Identify a user for analytics.
      *
-     * @param userId - The user identifier (e.g., metametrics ID)
      * @param traits - User traits/properties
      */
-    identify(userId: string, traits?: AnalyticsEventProperties): void;
+    identify(traits?: AnalyticsUserTraits): void;
     /**
-     * Track a page view.
+     * Track a page or screen view.
      *
-     * @param pageName - The name of the page
-     * @param properties - Page properties
-     */
-    trackPage(pageName: string, properties?: AnalyticsEventProperties): void;
-    /**
-     * Enable analytics tracking.
-     */
-    enable(): void;
-    /**
-     * Disable analytics tracking.
+     * @param name - The identifier/name of the page or screen being viewed (e.g., "home", "settings", "wallet")
+     * @param properties - Optional properties associated with the view
      */
-    disable(): void;
+    trackView(name: string, properties?: AnalyticsEventProperties): void;
     /**
      * Opt in to analytics.
      */