feat: MUSD-71 add segment events to musd conversion workflow (#24457)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**
Adds first set of events for the mUSD conversion flow.

### Events Added
- `MUSD_CONVERSION_CTA_CLICKED`
- `MUSD_FULLSCREEN_ANNOUNCEMENT_DISPLAYED`
- `MUSD_FULLSCREEN_ANNOUNCEMENT_BUTTON_CLICKED`
- `MUSD_CONVERSION_STATUS_UPDATED`
<!--
Write a short description of the changes included in this pull request,
also include relevant motivation and context. Have in mind the following
questions:
1. What is the reason for the change?
3. What is the improvement/solution?
-->

## **Changelog**

<!--
If this PR is not End-User-Facing and should not show up in the
CHANGELOG, you can choose to either:
1. Write `CHANGELOG entry: null`
2. Label with `no-changelog`

If this PR is End-User-Facing, please write a short User-Facing
description in the past tense like:
`CHANGELOG entry: Added a new tab for users to see their NFTs`
`CHANGELOG entry: Fixed a bug that was causing some NFTs to flicker`

(This helps the Release Engineer do their job more quickly and
accurately)
-->

CHANGELOG entry: add first iteration of mUSD conversion segment events

## **Related issues**

Fixes: [MUSD-71: Add segment events to mobile mUSD conversion
workflow](https://consensyssoftware.atlassian.net/browse/MUSD-71)

## **Manual testing steps**

```gherkin
Feature: mUSD conversion analytics tracking

  Scenario: user initiates mUSD conversion from a wallet CTA
    Given user is eligible to see a "Get/Convert to mUSD" call-to-action in the wallet

    When user taps the mUSD conversion call-to-action
    Then user is routed into the mUSD conversion flow (or the education screen on first view)
    And the app records the CTA click and subsequent conversion transaction status updates

  Scenario: user views the mUSD conversion education announcement and continues
    Given user is shown the mUSD conversion education screen

    When the user views the screen and taps a primary or secondary button
    Then the app records the announcement display and the button click
    And the user continues to the next step (continue) or returns (go back)
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

<!-- [screenshots/recordings] -->
N/A
### **After**

<!-- [screenshots/recordings] -->
N/A
## **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]
> Introduces first set of analytics for the mUSD conversion experience
and wires them across UI and transaction lifecycle.
> 
> - Adds new MetaMetrics events: `MUSD_CONVERSION_CTA_CLICKED`,
`MUSD_FULLSCREEN_ANNOUNCEMENT_DISPLAYED`,
`MUSD_FULLSCREEN_ANNOUNCEMENT_BUTTON_CLICKED`,
`MUSD_CONVERSION_STATUS_UPDATED`
> - Implements tracking in `EarnMusdConversionEducationView` (screen
viewed, primary/secondary button clicks), `MusdConversionAssetListCta`,
`MusdConversionAssetOverviewCta`, and `TokenListItem` CTAs
> - Tracks conversion transaction status in `useMusdConversionStatus`
(approved/confirmed/failed), including token, amount, chain, and network
name
> - Introduces `MUSD_EVENTS_CONSTANTS` and centralizes event
locations/providers under `earn/constants/events`, updating imports
accordingly
> - Minor hook updates (`useMusdBalance` memoization) and Earn views
import fixes; no UX changes
> - Adds extensive unit tests validating event emission across
views/hooks/CTAs
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
9857a7e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Nicholas Smith <nick.smith@consensys.net>

Author: Matt561

app/components/UI/Earn/Views/EarnInputView/EarnInputView.tsx

@@ -42,7 +42,7 @@ import { getStakingNavbar } from '../../../Navbar';
 import ScreenLayout from '../../../Ramp/Aggregator/components/ScreenLayout';
 import QuickAmounts from '../../../Stake/components/QuickAmounts';
 import { EVENT_PROVIDERS } from '../../../Stake/constants/events';
-import { EVENT_LOCATIONS } from '../../constants/events';
+import { EVENT_LOCATIONS } from '../../constants/events/earnEvents';
 import usePoolStakedDeposit from '../../../Stake/hooks/usePoolStakedDeposit';
 import EarnTokenSelector from '../../components/EarnTokenSelector';
 import InputDisplay from '../../components/InputDisplay';

app/components/UI/Earn/Views/EarnLendingDepositConfirmationView/index.tsx

@@ -36,7 +36,10 @@ import { EARN_EXPERIENCES } from '../../constants/experiences';
 import { RootState } from '../../../../../reducers';
 import { selectNetworkConfigurationByChainId } from '../../../../../selectors/networkController';
 import { IMetaMetricsEvent } from '../../../../../core/Analytics';
-import { EVENT_LOCATIONS, EVENT_PROVIDERS } from '../../constants/events';
+import {
+  EVENT_LOCATIONS,
+  EVENT_PROVIDERS,
+} from '../../constants/events/earnEvents';
 import { ProgressStep } from './components/ProgressStepper';
 import BN from 'bnjs4';
 import { endTrace, trace, TraceName } from '../../../../../util/trace';

app/components/UI/Earn/Views/EarnLendingWithdrawalConfirmationView/index.tsx

@@ -35,7 +35,10 @@ import { getStakingNavbar } from '../../../Navbar';
 import AccountTag from '../../../Stake/components/StakingConfirmation/AccountTag/AccountTag';
 import ContractTag from '../../../Stake/components/StakingConfirmation/ContractTag/ContractTag';
 import { TokenI } from '../../../Tokens/types';
-import { EVENT_LOCATIONS, EVENT_PROVIDERS } from '../../constants/events';
+import {
+  EVENT_LOCATIONS,
+  EVENT_PROVIDERS,
+} from '../../constants/events/earnEvents';
 import { EARN_EXPERIENCES } from '../../constants/experiences';
 import useEarnToken from '../../hooks/useEarnToken';
 import { EarnTokenDetails } from '../../types/lending.types';

app/components/UI/Earn/Views/EarnMusdConversionEducationView/index.test.tsx

@@ -14,6 +14,12 @@ import { strings } from '../../../../../../locales/i18n';
 import { useMusdConversion } from '../../hooks/useMusdConversion';
 import { useParams } from '../../../../../util/navigation/navUtils';
 
+const FIXED_NOW_MS = 1730000000000;
+const mockTrackEvent = jest.fn();
+const mockCreateEventBuilder = jest.fn();
+const mockAddProperties = jest.fn();
+const mockBuild = jest.fn();
+
 jest.mock('@react-navigation/native', () => {
   const actualNav = jest.requireActual('@react-navigation/native');
   return {
@@ -47,6 +53,17 @@ jest.mock('../../hooks/useMusdConversion', () => ({
   useMusdConversion: jest.fn(),
 }));
 
+jest.mock('../../../../hooks/useMetrics', () => {
+  const actual = jest.requireActual('../../../../hooks/useMetrics');
+  return {
+    ...actual,
+    useMetrics: () => ({
+      trackEvent: mockTrackEvent,
+      createEventBuilder: mockCreateEventBuilder,
+    }),
+  };
+});
+
 jest.mock('../../../../../util/Logger', () => ({
   error: jest.fn(),
 }));
@@ -88,6 +105,7 @@ describe('EarnMusdConversionEducationView', () => {
     setOptions: jest.fn(),
     navigate: jest.fn(),
     goBack: jest.fn(),
+    canGoBack: jest.fn(() => true),
   };
 
   const mockRouteParams = {
@@ -101,6 +119,8 @@ describe('EarnMusdConversionEducationView', () => {
   beforeEach(() => {
     jest.clearAllMocks();
 
+    jest.spyOn(Date, 'now').mockReturnValue(FIXED_NOW_MS);
+
     mockUseDispatch.mockReturnValue(mockDispatch);
     // @ts-expect-error - partial mock of navigation is sufficient for testing
     mockUseNavigation.mockReturnValue(mockNavigation);
@@ -119,9 +139,16 @@ describe('EarnMusdConversionEducationView', () => {
         seen,
       },
     }));
+
+    mockBuild.mockReturnValue({ name: 'mock-built-event' });
+    mockAddProperties.mockImplementation(() => ({ build: mockBuild }));
+    mockCreateEventBuilder.mockImplementation(() => ({
+      addProperties: mockAddProperties,
+    }));
   });
 
   afterEach(() => {
+    jest.restoreAllMocks();
     jest.resetAllMocks();
   });
 
@@ -249,6 +276,131 @@ describe('EarnMusdConversionEducationView', () => {
     });
   });
 
+  describe('MetaMetrics', () => {
+    it('tracks fullscreen announcement displayed event once per visit', () => {
+      const { MetaMetricsEvents } = jest.requireActual(
+        '../../../../hooks/useMetrics',
+      );
+
+      const { unmount } = renderWithProvider(
+        <EarnMusdConversionEducationView />,
+        { state: {} },
+      );
+
+      expect(mockCreateEventBuilder).toHaveBeenCalledTimes(1);
+      expect(mockCreateEventBuilder).toHaveBeenCalledWith(
+        MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_DISPLAYED,
+      );
+
+      expect(mockAddProperties).toHaveBeenCalledTimes(1);
+      expect(mockAddProperties).toHaveBeenCalledWith({
+        location: 'conversion_education_screen',
+      });
+
+      expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+      expect(mockTrackEvent).toHaveBeenCalledWith({
+        name: 'mock-built-event',
+      });
+
+      unmount();
+
+      renderWithProvider(<EarnMusdConversionEducationView />, { state: {} });
+
+      expect(mockCreateEventBuilder).toHaveBeenCalledTimes(2);
+      expect(mockCreateEventBuilder).toHaveBeenNthCalledWith(
+        2,
+        MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_DISPLAYED,
+      );
+
+      expect(mockAddProperties).toHaveBeenCalledTimes(2);
+      expect(mockAddProperties).toHaveBeenNthCalledWith(2, {
+        location: 'conversion_education_screen',
+      });
+
+      expect(mockTrackEvent).toHaveBeenCalledTimes(2);
+      expect(mockTrackEvent).toHaveBeenNthCalledWith(2, {
+        name: 'mock-built-event',
+      });
+    });
+
+    it('tracks fullscreen announcement button clicked event when continue button is pressed', async () => {
+      const { MetaMetricsEvents } = jest.requireActual(
+        '../../../../hooks/useMetrics',
+      );
+
+      const { getByText } = renderWithProvider(
+        <EarnMusdConversionEducationView />,
+        { state: {} },
+      );
+
+      mockTrackEvent.mockClear();
+      mockCreateEventBuilder.mockClear();
+      mockAddProperties.mockClear();
+      mockBuild.mockClear();
+
+      await act(async () => {
+        fireEvent.press(
+          getByText(strings('earn.musd_conversion.education.primary_button')),
+        );
+      });
+
+      await waitFor(() => {
+        expect(mockCreateEventBuilder).toHaveBeenCalledTimes(1);
+        expect(mockCreateEventBuilder).toHaveBeenCalledWith(
+          MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_BUTTON_CLICKED,
+        );
+
+        expect(mockAddProperties).toHaveBeenCalledTimes(1);
+        expect(mockAddProperties).toHaveBeenCalledWith({
+          location: 'conversion_education_screen',
+          button_type: 'primary',
+          button_text: strings('earn.musd_conversion.education.primary_button'),
+          redirects_to: 'custom_amount_screen',
+        });
+
+        expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+        expect(mockTrackEvent).toHaveBeenCalledWith({
+          name: 'mock-built-event',
+        });
+      });
+    });
+
+    it('tracks fullscreen announcement button clicked event when go back button is pressed', () => {
+      const { MetaMetricsEvents } = jest.requireActual(
+        '../../../../hooks/useMetrics',
+      );
+
+      const { getByText } = renderWithProvider(
+        <EarnMusdConversionEducationView />,
+        { state: {} },
+      );
+
+      mockTrackEvent.mockClear();
+      mockCreateEventBuilder.mockClear();
+      mockAddProperties.mockClear();
+      mockBuild.mockClear();
+
+      fireEvent.press(
+        getByText(strings('earn.musd_conversion.education.secondary_button')),
+      );
+
+      expect(mockCreateEventBuilder).toHaveBeenCalledTimes(1);
+      expect(mockCreateEventBuilder).toHaveBeenCalledWith(
+        MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_BUTTON_CLICKED,
+      );
+
+      expect(mockAddProperties).toHaveBeenCalledTimes(1);
+      expect(mockAddProperties).toHaveBeenCalledWith({
+        location: 'conversion_education_screen',
+        button_type: 'secondary',
+        button_text: strings('earn.musd_conversion.education.secondary_button'),
+      });
+
+      expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+      expect(mockTrackEvent).toHaveBeenCalledWith({ name: 'mock-built-event' });
+    });
+  });
+
   describe('error handling', () => {
     it('logs error when initiateConversion throws error', async () => {
       const testError = new Error('Conversion failed');

app/components/UI/Earn/Views/EarnMusdConversionEducationView/index.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useMemo } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
 import { Hex } from '@metamask/utils';
 import { useDispatch } from 'react-redux';
 import { View, Image, useColorScheme } from 'react-native';
@@ -25,7 +25,8 @@ import {
   ButtonVariant as DesignSystemButtonVariant,
 } from '@metamask/design-system-react-native';
 import { strings } from '../../../../../../locales/i18n';
-
+import { MetaMetricsEvents, useMetrics } from '../../../../hooks/useMetrics';
+import { MUSD_EVENTS_CONSTANTS } from '../../constants/events';
 interface EarnMusdConversionEducationViewRouteParams {
   /**
    * The payment token to preselect in the confirmation screen
@@ -58,6 +59,8 @@ const EarnMusdConversionEducationView = () => {
 
   const colorScheme = useColorScheme();
 
+  const { trackEvent, createEventBuilder } = useMetrics();
+
   const backgroundImage = useMemo(
     () =>
       colorScheme === 'dark'
@@ -66,8 +69,74 @@ const EarnMusdConversionEducationView = () => {
     [colorScheme],
   );
 
+  const { BUTTON_TYPES, EVENT_LOCATIONS } = MUSD_EVENTS_CONSTANTS;
+
+  const submitScreenViewedEvent = useCallback(() => {
+    trackEvent(
+      createEventBuilder(
+        MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_DISPLAYED,
+      )
+        .addProperties({
+          location: EVENT_LOCATIONS.CONVERSION_EDUCATION_SCREEN,
+        })
+        .build(),
+    );
+  }, [
+    EVENT_LOCATIONS.CONVERSION_EDUCATION_SCREEN,
+    createEventBuilder,
+    trackEvent,
+  ]);
+
+  const hasSubmittedScreenViewedEventRef = useRef(false);
+
+  useEffect(() => {
+    if (hasSubmittedScreenViewedEventRef.current) {
+      return;
+    }
+    hasSubmittedScreenViewedEventRef.current = true;
+    submitScreenViewedEvent();
+  }, [submitScreenViewedEvent]);
+
+  const submitContinuePressedEvent = useCallback(() => {
+    trackEvent(
+      createEventBuilder(
+        MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_BUTTON_CLICKED,
+      )
+        .addProperties({
+          location: EVENT_LOCATIONS.CONVERSION_EDUCATION_SCREEN,
+          button_type: BUTTON_TYPES.PRIMARY,
+          button_text: strings('earn.musd_conversion.education.primary_button'),
+          redirects_to: EVENT_LOCATIONS.CUSTOM_AMOUNT_SCREEN, // Redirects to custom amount screen.
+        })
+        .build(),
+    );
+  }, [
+    trackEvent,
+    createEventBuilder,
+    EVENT_LOCATIONS.CONVERSION_EDUCATION_SCREEN,
+    EVENT_LOCATIONS.CUSTOM_AMOUNT_SCREEN,
+    BUTTON_TYPES.PRIMARY,
+  ]);
+
+  const submitGoBackPressedEvent = () => {
+    trackEvent(
+      createEventBuilder(
+        MetaMetricsEvents.MUSD_FULLSCREEN_ANNOUNCEMENT_BUTTON_CLICKED,
+      )
+        .addProperties({
+          location: EVENT_LOCATIONS.CONVERSION_EDUCATION_SCREEN,
+          button_type: BUTTON_TYPES.SECONDARY,
+          button_text: strings(
+            'earn.musd_conversion.education.secondary_button',
+          ),
+        })
+        .build(),
+    );
+  };
+
   const handleContinue = useCallback(async () => {
     try {
+      submitContinuePressedEvent();
       // Mark education as seen so it won't show again
       dispatch(setMusdConversionEducationSeen(true));
 
@@ -91,9 +160,16 @@ const EarnMusdConversionEducationView = () => {
         '[mUSD Conversion Education] Failed to initiate conversion',
       );
     }
-  }, [dispatch, initiateConversion, outputChainId, preferredPaymentToken]);
+  }, [
+    dispatch,
+    initiateConversion,
+    outputChainId,
+    preferredPaymentToken,
+    submitContinuePressedEvent,
+  ]);
 
   const handleGoBack = () => {
+    submitGoBackPressedEvent();
     if (navigation.canGoBack()) {
       navigation.goBack();
     }

app/components/UI/Earn/Views/EarnWithdrawInputView/EarnWithdrawInputView.tsx

@@ -34,7 +34,10 @@ import useEarnWithdrawInput from '../../../Earn/hooks/useEarnWithdrawInput';
 import { getStakingNavbar } from '../../../Navbar';
 import ScreenLayout from '../../../Ramp/Aggregator/components/ScreenLayout';
 import QuickAmounts from '../../../Stake/components/QuickAmounts';
-import { EVENT_LOCATIONS, EVENT_PROVIDERS } from '../../constants/events';
+import {
+  EVENT_LOCATIONS,
+  EVENT_PROVIDERS,
+} from '../../constants/events/earnEvents';
 import usePoolStakedUnstake from '../../../Stake/hooks/usePoolStakedUnstake';
 import { StakeNavigationParamsList } from '../../../Stake/types';
 import EarnTokenSelector from '../../components/EarnTokenSelector';

app/components/UI/Earn/components/Earnings/index.tsx

@@ -19,7 +19,7 @@ import { useStyles } from '../../../../../component-library/hooks';
 import Routes from '../../../../../constants/navigation/Routes';
 import { MetaMetricsEvents } from '../../../../hooks/useMetrics';
 import EarnMaintenanceBanner from '../../../Earn/components/EarnMaintenanceBanner';
-import { EVENT_LOCATIONS } from '../../../Earn/constants/events';
+import { EVENT_LOCATIONS } from '../../constants/events/earnEvents';
 import useEarnings from '../../../Earn/hooks/useEarnings';
 import {
   selectPooledStakingServiceInterruptionBannerEnabledFlag,

app/components/UI/Earn/components/EmptyStateCta/EmptyStateCta.test.tsx

@@ -9,7 +9,10 @@ import { strings } from '../../../../../../locales/i18n';
 import { act, fireEvent } from '@testing-library/react-native';
 import { MetaMetricsEvents, useMetrics } from '../../../../hooks/useMetrics';
 import { MetricsEventBuilder } from '../../../../../core/Analytics/MetricsEventBuilder';
-import { EVENT_LOCATIONS, EVENT_PROVIDERS } from '../../constants/events';
+import {
+  EVENT_LOCATIONS,
+  EVENT_PROVIDERS,
+} from '../../constants/events/earnEvents';
 import {
   selectPooledStakingEnabledFlag,
   selectStablecoinLendingEnabledFlag,

app/components/UI/Earn/components/EmptyStateCta/index.tsx

@@ -21,7 +21,10 @@ import { getDecimalChainId } from '../../../../../util/networks';
 import { MetaMetricsEvents, useMetrics } from '../../../../hooks/useMetrics';
 import { useStyles } from '../../../../hooks/useStyles';
 import { TokenI } from '../../../Tokens/types';
-import { EVENT_LOCATIONS, EVENT_PROVIDERS } from '../../constants/events';
+import {
+  EVENT_LOCATIONS,
+  EVENT_PROVIDERS,
+} from '../../constants/events/earnEvents';
 import { selectStablecoinLendingEnabledFlag } from '../../selectors/featureFlags';
 import { parseFloatSafe } from '../../utils/number';
 import styleSheet from './EmptyStateCta.styles';