refactor(analytics): migrate Batch 3-17: mobile-platform (#26679)

## **Description**

Phase 3 analytics migration (Batch 3-17): migrate Sample Feature's
components and hooks from `useMetrics`/`MetricsEventBuilder` to the new
`useAnalytics`/`AnalyticsEventBuilder` analytics system.

**Reason**: Deprecate MetaMetrics in favour of the shared analytics
utility and AnalyticsController.

**Changes**: `SamplePetNamesForm`, `SampleCounterPane`, and
`SampleFeatureDevSettingsEntryPoint` now use `useAnalytics()` from
`app/components/hooks/useAnalytics/useAnalytics` and
`createEventBuilder` from the hook instead of `useMetrics()` and
`MetricsEventBuilder`; test mocks updated to mock the `useAnalytics`
hook with a chainable builder instead of `useMetrics`.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/MCWP-302 (Batch
3-17)

## **Manual testing steps**

```gherkin
Feature: Sample Feature analytics

  Scenario: user triggers a Sample Feature flow event
    Given app is open and user is in a Sample Feature flow

    When user performs an action that triggers analytics (e.g. increment counter, add pet name, navigate to sample feature)
    Then the event is tracked on Mixpanel
```

## **Screenshots/Recordings**

N/A – analytics migration, no UI change.

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [x] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: this is a refactor of analytics event building/tracking in a
non-production sample feature, with corresponding unit test updates.
Main risk is mis-tracked or missing events due to the new
builder/mocking semantics.
> 
> **Overview**
> Updates SampleFeature event tracking to use `useAnalytics()` and its
`createEventBuilder` instead of `useMetrics()`/`MetricsEventBuilder` in
`SampleCounterPane`, `SamplePetNamesForm`, and the dev-settings entry
point.
> 
> Adjusts analytics event definitions (`analytics/events.ts`) and
rewrites unit tests to mock/verify the new `useAnalytics` hook and
builder chaining, plus updates SampleFeature docs/e2e docs to refer to
**Analytics** (not MetaMetrics).
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
2dce2e4. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: NicolasMassart

app/features/SampleFeature/README.md

@@ -41,7 +41,7 @@ This feature demonstrates:
 - Form validation and error handling
 - Navigation patterns within the app
 - UI component library usage and styling
-- MetaMetrics tracking implementation
+- Analytics tracking implementation
 - Performance tracing patterns and monitoring
 - Comprehensive unit testing
 - End-to-end testing
@@ -66,7 +66,7 @@ The SampleFeature's structure mirrors the main `/app` directory. This helps devs
 
 ```
 app/features/SampleFeature/
-├── analytics/              # MetaMetrics event definitions
+├── analytics/              # Analytics event definitions
 │   └── events.ts
 ├── components/             # React components
 │   ├── hooks/             # Custom React hooks
@@ -109,7 +109,7 @@ A simple counter implementation demonstrating:
 - Redux Toolkit state management
 - Custom hooks (`useSampleCounter`)
 - Action dispatching
-- MetaMetrics event tracking
+- Analytics event tracking
 
 **Key Files:**
 
@@ -208,14 +208,13 @@ The feature extensively uses the MetaMask component library:
 - Follows MetaMask design system
 - Responsive layout with KeyboardAwareScrollView
 
-## MetaMetrics Tracking
+## Analytics Tracking
 
 Events are defined in `analytics/events.ts` following the event builder pattern:
 
 - Centralized event definitions in a dedicated analytics module
 - Event builder helper functions for consistent event creation
-- Type-safe event generation using the `generateOpt` utility
-- Integration with the global MetaMetrics system
+- Integration with the `useAnalytics` hook and `AnalyticsEventBuilder`
 - Separation of event definition from event dispatching
 
 ### Privacy Considerations
@@ -424,7 +423,7 @@ The SampleFeature demonstrates comprehensive testing patterns and best practices
 - Module mocking for native dependencies
 - Redux store mocking with `configureStore`
 - Navigation mocking for testing navigation flows
-- MetaMetrics tracking mock verification
+- Analytics tracking mock verification
 - Controller mocking for isolated component tests
 
 **Best Practices Demonstrated:**

app/features/SampleFeature/analytics/events.ts

@@ -1,6 +1,6 @@
 import {
   generateOpt,
-  EVENT_NAME as METRICS_EVENT_NAME,
+  EVENT_NAME as ANALYTICS_EVENT_NAME,
 } from '../../../core/Analytics/MetaMetrics.events';
 
 // Feature-specific event names (match EVENT_NAME style: SCREAMING_SNAKE_CASE keys, Initial Case string values with spaces)
@@ -13,7 +13,7 @@ export enum EVENT_NAME {
 
 // Helper to create events (type-casting to global event name type if needed)
 const createEvent = (name: EVENT_NAME) =>
-  generateOpt(name as unknown as METRICS_EVENT_NAME);
+  generateOpt(name as unknown as ANALYTICS_EVENT_NAME);
 
 // Export your events for use in the feature
 export const SAMPLE_FEATURE_EVENTS = {

app/features/SampleFeature/components/views/SampleCounterPane/SampleCounterPane.test.tsx

@@ -3,28 +3,15 @@ import { fireEvent, waitFor } from '@testing-library/react-native';
 import renderWithProvider from '../../../../../util/test/renderWithProvider';
 import { SampleCounterPane } from './SampleCounterPane';
 import { strings } from '../../../../../../locales/i18n';
-import useMetrics from '../../../../../components/hooks/useMetrics/useMetrics';
 import { SAMPLE_FEATURE_EVENTS } from '../../../analytics/events';
-import { MetricsEventBuilder } from '../../../../../core/Analytics/MetricsEventBuilder.ts';
+import { useAnalytics } from '../../../../../components/hooks/useAnalytics/useAnalytics';
 
-/**
- * Mock implementation for react-native Linking module
- * Required for testing components that use deep linking functionality
- */
 jest.mock('react-native/Libraries/Linking/Linking', () => ({
   addEventListener: jest.fn(() => ({ remove: jest.fn() })),
 }));
 
-/**
- * Mock implementation of the increment function
- * Used to verify counter increment functionality
- */
 const mockIncrement = jest.fn();
 
-/**
- * Mock implementation of the useSampleCounter hook
- * Provides a controlled test environment for the counter functionality
- */
 jest.mock('../../hooks/useSampleCounter/useSampleCounter', () => ({
   __esModule: true,
   useSampleCounter: () => ({
@@ -33,32 +20,11 @@ jest.mock('../../hooks/useSampleCounter/useSampleCounter', () => ({
   }),
 }));
 
-jest.mock('../../../../../components/hooks/useMetrics/useMetrics');
+const mockAnalytics = jest.mocked(useAnalytics)();
 
-const mockTrackEvent = jest.fn();
-
-/**
- * Test suite for SampleCounterPane component
- *
- * @group Components
- * @group SampleCounterPane
- */
 describe('SampleCounterPane', () => {
   beforeEach(() => {
     jest.clearAllMocks();
-    (useMetrics as jest.MockedFn<typeof useMetrics>).mockReturnValue({
-      trackEvent: mockTrackEvent,
-      createEventBuilder: MetricsEventBuilder.createEventBuilder,
-      enable: jest.fn(),
-      addTraitsToUser: jest.fn(),
-      createDataDeletionTask: jest.fn(),
-      checkDataDeleteStatus: jest.fn(),
-      getDeleteRegulationCreationDate: jest.fn(),
-      getDeleteRegulationId: jest.fn(),
-      isDataRecorded: jest.fn(),
-      isEnabled: jest.fn(),
-      getMetaMetricsId: jest.fn(),
-    });
   });
 
   /**
@@ -107,10 +73,9 @@ describe('SampleCounterPane', () => {
     fireEvent.press(getByTestId('sample-counter-pane-increment-button'));
 
     await waitFor(() => {
-      expect(mockTrackEvent).toHaveBeenCalledWith(
-        expect.objectContaining({
-          name: SAMPLE_FEATURE_EVENTS.COUNTER_INCREMENTED.category,
-        }),
+      expect(mockAnalytics.trackEvent).toHaveBeenCalled();
+      expect(mockAnalytics.createEventBuilder).toHaveBeenCalledWith(
+        SAMPLE_FEATURE_EVENTS.COUNTER_INCREMENTED,
       );
     });
   });

app/features/SampleFeature/components/views/SampleCounterPane/SampleCounterPane.tsx

@@ -10,8 +10,7 @@ import { useSampleCounter } from '../../hooks/useSampleCounter/useSampleCounter'
 import { strings } from '../../../../../../locales/i18n';
 import Card from '../../../../../component-library/components/Cards/Card';
 import { useStyles } from '../../../../../component-library/hooks';
-import useMetrics from '../../../../../components/hooks/useMetrics/useMetrics';
-import { MetricsEventBuilder } from '../../../../../core/Analytics/MetricsEventBuilder';
+import { useAnalytics } from '../../../../../components/hooks/useAnalytics/useAnalytics';
 import { SAMPLE_FEATURE_EVENTS } from '../../../analytics/events';
 
 /**
@@ -43,13 +42,11 @@ import { SAMPLE_FEATURE_EVENTS } from '../../../analytics/events';
 export function SampleCounterPane() {
   const { styles } = useStyles(styleSheet, {});
   const counter = useSampleCounter();
-  const { trackEvent } = useMetrics();
+  const { trackEvent, createEventBuilder } = useAnalytics();
 
   const incrementCount = () => {
     trackEvent(
-      MetricsEventBuilder.createEventBuilder(
-        SAMPLE_FEATURE_EVENTS.COUNTER_INCREMENTED,
-      ).build(),
+      createEventBuilder(SAMPLE_FEATURE_EVENTS.COUNTER_INCREMENTED).build(),
     );
     counter.incrementCount();
   };

app/features/SampleFeature/components/views/SampleFeatureDevSettingsEntryPoint/SampleFeatureDevSettingsEntryPoint.tsx

@@ -14,12 +14,12 @@ import Button, {
 import { MetaMetricsEvents } from '../../../../../core/Analytics';
 import { useNavigation } from '@react-navigation/native';
 import styleSheet from './SampleFeatureDevSettingsEntryPoint.styles';
-import { useMetrics } from '../../../../../components/hooks/useMetrics';
+import { useAnalytics } from '../../../../../components/hooks/useAnalytics/useAnalytics';
 
 function NavigateToSampleFeature() {
   const theme = useTheme();
   const { styles } = useStyles(styleSheet, { theme });
-  const { trackEvent, createEventBuilder } = useMetrics();
+  const { trackEvent, createEventBuilder } = useAnalytics();
   const navigation = useNavigation();
 
   const onPressNavigate = () => {

app/features/SampleFeature/components/views/SamplePetNames/SamplePetNamesForm.test.tsx

@@ -10,9 +10,8 @@ jest.mock('react-native/Libraries/Linking/Linking', () => ({
 
 import { SamplePetNamesForm } from './SamplePetNamesForm';
 import Engine from '../../../../../core/Engine';
-import useMetrics from '../../../../../components/hooks/useMetrics/useMetrics';
 import { SAMPLE_FEATURE_EVENTS } from '../../../analytics/events';
-import { MetricsEventBuilder } from '../../../../../core/Analytics/MetricsEventBuilder.ts';
+import { useAnalytics } from '../../../../../components/hooks/useAnalytics/useAnalytics';
 
 jest.mock('../../../../../core/Engine', () => ({
   context: {
@@ -22,44 +21,25 @@ jest.mock('../../../../../core/Engine', () => ({
   },
 }));
 
-// Mock the useSamplePetNames hook
 jest.mock('../../hooks/useSamplePetNames', () => ({
   useSamplePetNames: jest.fn(),
 }));
 
-jest.mock('../../../../../components/hooks/useMetrics/useMetrics');
-
 import { useSamplePetNames } from '../../hooks/useSamplePetNames';
 
+const mockAnalytics = jest.mocked(useAnalytics)();
+
 const mockUseSamplePetNames = useSamplePetNames as jest.MockedFunction<
   typeof useSamplePetNames
 >;
 
-const mockTrackEvent = jest.fn();
-
 describe('SamplePetNamesForm', () => {
   let alertSpy: jest.SpyInstance;
 
   beforeEach(() => {
     jest.clearAllMocks();
-    // Default mock return value - no existing pet names
     mockUseSamplePetNames.mockReturnValue({ petNames: [] });
-    // Create spy on Alert.alert
     alertSpy = jest.spyOn(Alert, 'alert').mockImplementation(jest.fn());
-
-    (useMetrics as jest.MockedFn<typeof useMetrics>).mockReturnValue({
-      trackEvent: mockTrackEvent,
-      createEventBuilder: MetricsEventBuilder.createEventBuilder,
-      enable: jest.fn(),
-      addTraitsToUser: jest.fn(),
-      createDataDeletionTask: jest.fn(),
-      checkDataDeleteStatus: jest.fn(),
-      getDeleteRegulationCreationDate: jest.fn(),
-      getDeleteRegulationId: jest.fn(),
-      isDataRecorded: jest.fn(),
-      isEnabled: jest.fn(),
-      getMetaMetricsId: jest.fn(),
-    });
   });
 
   afterEach(() => {
@@ -130,15 +110,16 @@ describe('SamplePetNamesForm', () => {
 
     // Assert
     await waitFor(() => {
-      expect(mockTrackEvent).toHaveBeenCalledWith(
-        expect.objectContaining({
-          name: SAMPLE_FEATURE_EVENTS.PETNAME_ADDED.category,
-          properties: {
-            totalPetNames: 0,
-            chainId: '0x1',
-          },
-        }),
+      expect(mockAnalytics.trackEvent).toHaveBeenCalled();
+      expect(mockAnalytics.createEventBuilder).toHaveBeenCalledWith(
+        SAMPLE_FEATURE_EVENTS.PETNAME_ADDED,
       );
+      const builder = jest.mocked(mockAnalytics.createEventBuilder).mock
+        .results[0].value;
+      expect(builder.addProperties).toHaveBeenCalledWith({
+        totalPetNames: 0,
+        chainId: '0x1',
+      });
     });
   });
 
@@ -246,15 +227,16 @@ describe('SamplePetNamesForm', () => {
 
     // Assert
     await waitFor(() => {
-      expect(mockTrackEvent).toHaveBeenCalledWith(
-        expect.objectContaining({
-          name: SAMPLE_FEATURE_EVENTS.PETNAME_UPDATED.category,
-          properties: {
-            totalPetNames: 1,
-            chainId: '0x1',
-          },
-        }),
+      expect(mockAnalytics.trackEvent).toHaveBeenCalled();
+      expect(mockAnalytics.createEventBuilder).toHaveBeenCalledWith(
+        SAMPLE_FEATURE_EVENTS.PETNAME_UPDATED,
       );
+      const builder = jest.mocked(mockAnalytics.createEventBuilder).mock
+        .results[0].value;
+      expect(builder.addProperties).toHaveBeenCalledWith({
+        totalPetNames: 1,
+        chainId: '0x1',
+      });
     });
   });
 });

app/features/SampleFeature/components/views/SamplePetNames/SamplePetNamesForm.tsx

@@ -10,8 +10,7 @@ import styleSheet from './SamplePetNamesForm.styles';
 import { strings } from '../../../../../../locales/i18n';
 import { SamplePetNamesFormContentProps } from './SamplePetNamesForm.types';
 import { useSamplePetNamesForm } from '../../hooks/useSamplePetNamesForm';
-import useMetrics from '../../../../../components/hooks/useMetrics/useMetrics';
-import { MetricsEventBuilder } from '../../../../../core/Analytics/MetricsEventBuilder';
+import { useAnalytics } from '../../../../../components/hooks/useAnalytics/useAnalytics';
 import { SAMPLE_FEATURE_EVENTS } from '../../../analytics/events';
 import trackErrorAsAnalytics from '../../../../../util/metrics/TrackError/trackErrorAsAnalytics';
 import { useSamplePetNames } from '../../hooks/useSamplePetNames';
@@ -57,7 +56,7 @@ export function SamplePetNamesForm({
 
   const { onSubmit, isValid, name, setName, setAddress, address } =
     useSamplePetNamesForm(chainId, initialAddress, initialName);
-  const { trackEvent } = useMetrics();
+  const { trackEvent, createEventBuilder } = useAnalytics();
   const { petNames } = useSamplePetNames(chainId);
 
   const submit = () => {
@@ -71,9 +70,7 @@ export function SamplePetNamesForm({
       if (isEditMode) {
         // User pressed existing pet name - direct update
         trackEvent(
-          MetricsEventBuilder.createEventBuilder(
-            SAMPLE_FEATURE_EVENTS.PETNAME_UPDATED,
-          )
+          createEventBuilder(SAMPLE_FEATURE_EVENTS.PETNAME_UPDATED)
             .addProperties({
               totalPetNames: petNames.length,
               chainId: chainId as string,
@@ -101,9 +98,7 @@ export function SamplePetNamesForm({
               text: strings('sample_feature.pet_name.update'),
               onPress: () => {
                 trackEvent(
-                  MetricsEventBuilder.createEventBuilder(
-                    SAMPLE_FEATURE_EVENTS.PETNAME_UPDATED,
-                  )
+                  createEventBuilder(SAMPLE_FEATURE_EVENTS.PETNAME_UPDATED)
                     .addProperties({
                       totalPetNames: petNames.length,
                       chainId: chainId as string,
@@ -119,9 +114,7 @@ export function SamplePetNamesForm({
     } else {
       // No duplicate - add new pet name
       trackEvent(
-        MetricsEventBuilder.createEventBuilder(
-          SAMPLE_FEATURE_EVENTS.PETNAME_ADDED,
-        )
+        createEventBuilder(SAMPLE_FEATURE_EVENTS.PETNAME_ADDED)
           .addProperties({
             totalPetNames: petNames.length,
             chainId: chainId as string,

app/features/SampleFeature/e2e/README.md

@@ -11,7 +11,7 @@ The Sample Feature is a development/testing feature that demonstrates:
 - Form validation and error handling
 - Navigation patterns within the app
 - UI component library usage and styling
-- Metametrics tracking
+- Analytics tracking
 - Unit testing
 - End-to-end testing