feat(perps): add missing analytics properties and fix source propagation (#27493)

## **Description**

Adds missing Segment/Mixpanel analytics data across Perps events and
fixes source propagation issues to ensure accurate attribution in
analytics dashboards.

### Motivation
Several Perps analytics parameters were missing or inconsistent in
Mixpanel:
- `PERP SCREEN VIEWED` had many `(not set)` source values
- Transaction events (`TRADE`, `CLOSE`) lacked source and order value
tracking
- `PERP RISK MANAGEMENT` didn't differentiate TP vs SL vs both
- Reusable components navigated without passing `source`, leading to
implicit/missing attribution
- `source` was sometimes propagated from earlier screens in the
navigation chain instead of reflecting the current screen

### Solution
1. **New analytics properties**: `open_order`, `order_value`,
`market_category`, `error_type`, `action` (tp/sl/tpsl, flip variants),
and `explore` source
2. **Source propagation fix**: Screens now always set themselves as the
`source` rather than forwarding from previous screens (e.g., Market List
→ Market Details uses `perp_markets`, not `explore`)
3. **Explicit source passing**: Reusable components
(`PerpsMarketTypeSection`, `PerpsWatchlistMarkets`, `PerpsCard`) now
accept `source` as a prop from parent screens instead of navigating
without it
4. **Tooltip context**: `button_location` for tooltip "Got it" clicks
now includes screen-specific context
5. **Documentation**: Updated
`docs/perps/perps-metametrics-reference.md` with all new properties and
source ownership best practices

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/TAT-2370

## **Manual testing steps**

```gherkin
Feature: Perps analytics source tracking

  Scenario: Source reflects current screen when navigating through multiple screens
    Given the user is on the Explore page
    When the user taps "View All" on the Perps section to open Market List
    And taps a market to open Market Details
    And taps Long to open the Trading screen
    Then PERPS_SCREEN_VIEWED for Market List has source = "explore"
    And PERPS_SCREEN_VIEWED for Market Details has source = "perp_markets"
    And PERPS_SCREEN_VIEWED for Trading has source = "perp_asset_screen"

  Scenario: Reusable components pass source from parent screen
    Given the user is on Perps Home
    When the user taps a market in the Crypto section
    Then PERPS_SCREEN_VIEWED for Market Details has source = "perps_home"

  Scenario: Trade transaction includes order value and source
    Given the user is on the Trading screen (from Market Details)
    When the user places a market order for 0.1 BTC at $60,000
    Then PERPS_TRADE_TRANSACTION includes source = "perp_asset_screen"
    And PERPS_TRADE_TRANSACTION includes order_value = 6000

  Scenario: Risk management event differentiates TP/SL
    Given the user has an open BTC position
    When the user sets both take profit and stop loss
    Then PERPS_RISK_MANAGEMENT includes action = "tpsl"

  Scenario: open_order parameter on screen viewed events
    Given the user has 3 open orders
    When the user views the Perps Home screen
    Then PERPS_SCREEN_VIEWED includes open_order = 3
```

## **Screenshots/Recordings**

N/A — Analytics-only changes, no UI modifications.

### **Before**

N/A

### **After**

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]
> **Medium Risk**
> Mostly analytics instrumentation changes, but they touch navigation
params and `TradingService` tracking for trade/close events, so
incorrect wiring could skew attribution or event schemas in production
dashboards.
> 
> **Overview**
> Improves Perps analytics attribution by **standardizing `source`
propagation** across navigation (market list/details/order/close flows),
including passing `source` explicitly through reusable components
(`PerpsMarketTypeSection`, `PerpsWatchlistMarkets`, tooltips, and
close-position routing).
> 
> Adds missing MetaMetrics properties across key screen views and
transactions: `open_order`/`open_position` counts on more screens,
`market_category` on market list, `order_value` for trade and close
transactions, and more specific `action` values for TP/SL updates and
flip-position direction; updates tests and the Perps MetaMetrics
reference docs accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
36cf38e. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: michalconsensys

app/components/UI/Perps/Views/PerpsClosePositionView/PerpsClosePositionView.tsx

@@ -86,7 +86,10 @@ const PerpsClosePositionView: React.FC = () => {
   const navigation = useNavigation();
   const route =
     useRoute<RouteProp<PerpsNavigationParamList, 'PerpsClosePosition'>>();
-  const { position } = route.params as { position: Position };
+  const { position, source: routeSource } = route.params as {
+    position: Position;
+    source?: string;
+  };
 
   const inputMethodRef = useRef<InputMethod>('default');
   const isAmountInitializedRef = useRef(false);
@@ -392,6 +395,7 @@ const PerpsClosePositionView: React.FC = () => {
         metamaskFee: feeResults.metamaskFee,
         estimatedPoints: rewardsState.estimatedPoints,
         inputMethod: inputMethodRef.current,
+        source: routeSource,
       },
       marketPrice: priceData[position.symbol]?.price,
       // Always pass slippage parameters for price context

app/components/UI/Perps/Views/PerpsHomeView/PerpsHomeView.test.tsx

@@ -230,6 +230,7 @@ jest.mock('@metamask/perps-controller', () => ({
     SOURCE: {
       MAIN_ACTION_BUTTON: 'main_action_button',
       HOMESCREEN_TAB: 'homescreen_tab',
+      PERPS_HOME: 'perps_home',
     },
     BUTTON_LOCATION: {
       PERPS_HOME: 'perps_home',
@@ -558,7 +559,7 @@ describe('PerpsHomeView', () => {
 
     expect(mockNavigateToMarketList).toHaveBeenCalledWith({
       defaultMarketTypeFilter: 'all',
-      source: PERPS_EVENT_VALUE.SOURCE.HOMESCREEN_TAB,
+      source: PERPS_EVENT_VALUE.SOURCE.PERPS_HOME,
       fromHome: true,
       button_clicked: 'magnifying_glass',
       button_location: 'perps_home',

app/components/UI/Perps/Views/PerpsHomeView/PerpsHomeView.tsx

@@ -210,6 +210,8 @@ const PerpsHomeView = () => {
         PERPS_EVENT_VALUE.SCREEN_TYPE.PERPS_HOME,
       [PERPS_EVENT_PROPERTY.SOURCE]: source,
       [PERPS_EVENT_PROPERTY.HAS_PERP_BALANCE]: hasPerpBalance,
+      [PERPS_EVENT_PROPERTY.OPEN_POSITION]: livePositions.positions.length,
+      [PERPS_EVENT_PROPERTY.OPEN_ORDER]: orders?.length || 0,
       ...(buttonClicked && {
         [PERPS_EVENT_PROPERTY.BUTTON_CLICKED]: buttonClicked,
       }),
@@ -235,7 +237,7 @@ const PerpsHomeView = () => {
     );
     perpsNavigation.navigateToMarketList({
       defaultMarketTypeFilter: 'all',
-      source: PERPS_EVENT_VALUE.SOURCE.HOMESCREEN_TAB,
+      source: PERPS_EVENT_VALUE.SOURCE.PERPS_HOME,
       fromHome: true,
       button_clicked: PERPS_EVENT_VALUE.BUTTON_CLICKED.MAGNIFYING_GLASS,
       button_location: PERPS_EVENT_VALUE.BUTTON_LOCATION.PERPS_HOME,
@@ -257,7 +259,7 @@ const PerpsHomeView = () => {
         .build(),
     );
     navigation.navigate(Routes.PERPS.TUTORIAL, {
-      source: PERPS_EVENT_VALUE.SOURCE.HOMESCREEN_TAB,
+      source: PERPS_EVENT_VALUE.SOURCE.PERPS_HOME,
     });
   }, [navigation, trackEvent, createEventBuilder]);
 
@@ -445,7 +447,7 @@ const PerpsHomeView = () => {
               <PerpsCard
                 key={`${position.symbol}-${index}`}
                 position={position}
-                source={PERPS_EVENT_VALUE.SOURCE.HOMESCREEN_TAB}
+                source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
               />
             ))}
           </View>
@@ -465,7 +467,7 @@ const PerpsHomeView = () => {
               <PerpsCard
                 key={order.orderId}
                 order={order}
-                source={PERPS_EVENT_VALUE.SOURCE.HOMESCREEN_TAB}
+                source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
               />
             ))}
           </View>
@@ -477,6 +479,7 @@ const PerpsHomeView = () => {
           isLoading={isLoading.markets}
           positions={positions}
           orders={orders}
+          source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
         />
 
         {/* Crypto Markets List */}
@@ -487,6 +490,7 @@ const PerpsHomeView = () => {
             marketType="crypto"
             sortBy={sortBy}
             isLoading={isLoading.markets}
+            source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
           />
         </View>
 
@@ -497,6 +501,7 @@ const PerpsHomeView = () => {
           marketType="commodities"
           sortBy={sortBy}
           isLoading={isLoading.markets}
+          source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
         />
 
         {/* Stocks Markets List */}
@@ -507,6 +512,7 @@ const PerpsHomeView = () => {
             marketType="stocks"
             sortBy={sortBy}
             isLoading={isLoading.markets}
+            source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
           />
         </View>
 
@@ -516,6 +522,7 @@ const PerpsHomeView = () => {
           markets={forexMarkets}
           marketType="forex"
           isLoading={isLoading.markets}
+          source={PERPS_EVENT_VALUE.SOURCE.PERPS_HOME}
         />
 
         {/* Recent Activity List */}

app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.test.tsx

@@ -1423,7 +1423,7 @@ describe('PerpsMarketDetailsView', () => {
       expect(mockNavigateToOrder).toHaveBeenCalledWith({
         direction: 'long',
         asset: 'BTC',
-        source: 'trade_action',
+        source: 'perp_asset_screen',
       });
     });
 
@@ -1459,7 +1459,7 @@ describe('PerpsMarketDetailsView', () => {
       expect(mockNavigateToOrder).toHaveBeenCalledWith({
         direction: 'short',
         asset: 'BTC',
-        source: 'trade_action',
+        source: 'perp_asset_screen',
       });
     });
 

app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.tsx

@@ -557,6 +557,7 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
       [PERPS_EVENT_PROPERTY.SOURCE]:
         source || PERPS_EVENT_VALUE.SOURCE.PERP_MARKETS,
       [PERPS_EVENT_PROPERTY.OPEN_POSITION]: existingPosition ? 1 : 0,
+      [PERPS_EVENT_PROPERTY.OPEN_ORDER]: openOrders.length,
       // A/B Test context (TAT-1937) - for baseline exposure tracking
       ...(isButtonColorTestEnabled && {
         [PERPS_EVENT_PROPERTY.AB_TEST_BUTTON_COLOR]: buttonColorVariant,
@@ -620,7 +621,7 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
       navigateBack();
     } else {
       // Fallback to markets list if no previous screen
-      navigateToHome(source);
+      navigateToHome(PERPS_EVENT_VALUE.SOURCE.PERP_ASSET_SCREEN);
     }
   };
 
@@ -700,7 +701,7 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
       navigateToOrder({
         direction,
         asset: market.symbol,
-        source: PERPS_EVENT_VALUE.SOURCE.TRADE_ACTION,
+        source: PERPS_EVENT_VALUE.SOURCE.PERP_ASSET_SCREEN,
       });
     },
     [
@@ -865,7 +866,10 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
       return;
     }
 
-    navigateToClosePosition(existingPosition);
+    navigateToClosePosition(
+      existingPosition,
+      PERPS_EVENT_VALUE.SOURCE.PERP_ASSET_SCREEN,
+    );
   }, [existingPosition, navigateToClosePosition, isEligible, track]);
 
   // Modify position handler - opens the modify action sheet
@@ -1526,6 +1530,7 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
           onClose={handleTooltipClose}
           contentKey={selectedTooltip}
           testID={PerpsMarketDetailsViewSelectorsIDs.BOTTOM_SHEET_TOOLTIP}
+          buttonLocation={PERPS_EVENT_VALUE.BUTTON_LOCATION.PERP_MARKET_DETAILS}
         />
       )}
 

app/components/UI/Perps/Views/PerpsMarketListView/PerpsMarketListView.tsx

@@ -104,10 +104,13 @@ const PerpsMarketListView = ({
       if (onMarketSelect) {
         onMarketSelect(market);
       } else {
-        perpsNavigation.navigateToMarketDetails(market, route.params?.source);
+        perpsNavigation.navigateToMarketDetails(
+          market,
+          PERPS_EVENT_VALUE.SOURCE.PERP_MARKETS,
+        );
       }
     },
-    [onMarketSelect, perpsNavigation, route.params?.source],
+    [onMarketSelect, perpsNavigation],
   );
 
   // Compute available categories based on market counts (hide empty categories)
@@ -192,6 +195,7 @@ const PerpsMarketListView = ({
         PERPS_EVENT_VALUE.SCREEN_TYPE.MARKET_LIST,
       [PERPS_EVENT_PROPERTY.SOURCE]: source,
       [PERPS_EVENT_PROPERTY.HAS_PERP_BALANCE]: hasPerpBalance,
+      [PERPS_EVENT_PROPERTY.MARKET_CATEGORY]: marketTypeFilter,
       ...(buttonClicked && {
         [PERPS_EVENT_PROPERTY.BUTTON_CLICKED]: buttonClicked,
       }),

app/components/UI/Perps/Views/PerpsOrderBookView/PerpsOrderBookView.test.tsx

@@ -775,6 +775,7 @@ describe('PerpsOrderBookView', () => {
 
       expect(mockNavigateToClosePosition).toHaveBeenCalledWith(
         mockLongPosition,
+        'order_book',
       );
     });
 

app/components/UI/Perps/Views/PerpsOrderBookView/PerpsOrderBookView.tsx

@@ -298,6 +298,7 @@ const PerpsOrderBookView: React.FC<PerpsOrderBookViewProps> = ({
         PERPS_EVENT_VALUE.SCREEN_TYPE.ORDER_BOOK,
       [PERPS_EVENT_PROPERTY.ASSET]: symbol || '',
       [PERPS_EVENT_PROPERTY.SOURCE]: PERPS_EVENT_VALUE.SOURCE.PERP_ASSET_SCREEN,
+      [PERPS_EVENT_PROPERTY.OPEN_POSITION]: existingPosition ? 1 : 0,
     },
   });
 
@@ -465,7 +466,10 @@ const PerpsOrderBookView: React.FC<PerpsOrderBookViewProps> = ({
       return;
     }
 
-    navigateToClosePosition(existingPosition);
+    navigateToClosePosition(
+      existingPosition,
+      PERPS_EVENT_VALUE.SOURCE.ORDER_BOOK,
+    );
   }, [existingPosition, navigateToClosePosition, isEligible, track]);
 
   // Handle Modify position button press
@@ -779,6 +783,7 @@ const PerpsOrderBookView: React.FC<PerpsOrderBookViewProps> = ({
               onClose={handleTooltipClose}
               contentKey={selectedTooltip}
               testID={PerpsOrderBookViewSelectorsIDs.BOTTOM_SHEET_TOOLTIP}
+              buttonLocation={PERPS_EVENT_VALUE.BUTTON_LOCATION.ORDER_BOOK}
             />
           </Modal>
         </View>

app/components/UI/Perps/Views/PerpsOrderView/PerpsOrderView.tsx

@@ -381,6 +381,7 @@ const PerpsOrderViewContentBase: React.FC<PerpsOrderViewContentProps> = ({
         : PERPS_EVENT_VALUE.DIRECTION.SHORT,
     [PERPS_EVENT_PROPERTY.SOURCE]:
       source ?? PERPS_EVENT_VALUE.SOURCE.PERP_ASSET_SCREEN,
+    [PERPS_EVENT_PROPERTY.OPEN_POSITION]: currentMarketPosition ? 1 : 0,
     ...(routeAbTestTokenDetailsLayout && {
       ab_tests: {
         assetsASSETS2493AbtestTokenDetailsLayout: routeAbTestTokenDetailsLayout,
@@ -1788,6 +1789,7 @@ const PerpsOrderViewContentBase: React.FC<PerpsOrderViewContentProps> = ({
           contentKey={selectedTooltip}
           testID={PerpsOrderViewSelectorsIDs.BOTTOM_SHEET_TOOLTIP}
           key={selectedTooltip}
+          buttonLocation={PERPS_EVENT_VALUE.BUTTON_LOCATION.PERPS_ASSET_SCREEN}
           data={
             selectedTooltip === 'fees'
               ? {

app/components/UI/Perps/Views/PerpsSelectModifyActionView/PerpsSelectModifyActionView.test.tsx

@@ -184,7 +184,10 @@ describe('PerpsSelectModifyActionView', () => {
 
     fireEvent.press(screen.getByTestId('reduce-position'));
 
-    expect(mockNavigateToClosePosition).toHaveBeenCalledWith(mockLongPosition);
+    expect(mockNavigateToClosePosition).toHaveBeenCalledWith(
+      mockLongPosition,
+      'position_screen',
+    );
   });
 
   it('calls onReversePosition when flip_position is selected with callback', () => {