feat: Add geo-blocking analytics tracking (MetaMask#22126)

# Geoblock Analytics Implementation

## Overview

This PR implements analytics tracking for geoblocking events in Predict,
allowing us to understand when and where users are blocked from
performing actions due to geographic restrictions.

CHANGELOG entry: null

## Changes

### 1. State Structure Refactoring

**Consolidated eligibility and geoblock data into a single nested
structure:**

```typescript
// Before
eligibility: { [key: string]: boolean }
geoBlockData: { [key: string]: { country?: string } }

// After
eligibility: {
  [key: string]: {
    eligible: boolean;
    country?: string;
  }
}
```

**Benefits:**
- Simplified state management - one source of truth
- Atomic updates - eligible status and country always in sync
- Easier to consume - no need to access two separate state objects

### 2. Analytics Event Implementation

**Event:** `PREDICT_GEO_BLOCKED_TRIGGERED`

**Properties:**
- `country` - The country code where the user is located (from geoblock
API)
- `attempted_action` - The action the user tried to perform

**Attempted Actions:**
- `deposit` - User tried to add funds
- `predict_action` - User tried to place a prediction
- `cashout` - User tried to cash out a position
- `claim` - User tried to claim winnings
- `withdraw` - User tried to withdraw funds (not currently guarded)

### 3. Integration Points

**Guarded Actions:**
All actions that require eligibility checks use `executeGuardedAction`
from `usePredictActionGuard` hook:

```typescript
executeGuardedAction(
  () => {
    // Action logic
  },
  { attemptedAction: PredictEventValues.ATTEMPTED_ACTION.DEPOSIT }
);
```

**Components Updated:**
- ✅ `PredictBalance.tsx` - Add funds (deposit)
- ✅ `PredictAddFundsSheet.tsx` - Add funds (deposit)
- ✅ `PredictMarketDetails.tsx` - Buy (predict), Claim
- ✅ `PredictPositionsHeader.tsx` - Claim
- ✅ `PredictPositionDetail.tsx` - Cash out
- ✅ `PredictMarketSingle.tsx` - Buy (predict)
- ✅ `PredictMarketOutcome.tsx` - Buy (predict)
- ✅ `PredictMarketMultiple.tsx` - Buy (predict)

### 4. Controller Updates

**`PredictController.ts`:**
- `refreshEligibility()` - Now stores both `eligible` and `country`
together
- `trackGeoBlockedEvent()` - New method to track analytics when user is
blocked
- Updated to use consolidated eligibility state

**`usePredictEligibility.ts` hook:**
- Now returns both `isEligible` and `country`
- Simplifies component consumption

### 5. Testing

**All tests updated and passing:**
- ✅ PredictController tests (1687 tests)
- ✅ usePredictEligibility tests
- ✅ Component tests updated for new hook signature
- ✅ Test suites: 67 passed

## Data Flow

```
User Action Attempt
       ↓
executeGuardedAction
       ↓
Check eligibility (from state)
       ↓
   Blocked? → Yes → trackGeoBlockedEvent(country, attemptedAction)
       ↓                        ↓
       No              Analytics Event Sent
       ↓
Execute Action
```

## Analytics Dashboard

**To query geoblock events in the analytics dashboard:**

```sql
SELECT 
  country,
  attempted_action,
  COUNT(*) as blocked_count,
  DATE(timestamp) as date
FROM events
WHERE event_name = 'PREDICT_GEO_BLOCKED_TRIGGERED'
GROUP BY country, attempted_action, DATE(timestamp)
ORDER BY blocked_count DESC
```

**Key Metrics:**
- Most blocked countries
- Most common blocked actions
- Trends over time
- Conversion rates by geography

## Example Event

```json
{
  "event": "PREDICT_GEO_BLOCKED_TRIGGERED",
  "properties": {
    "country": "US",
    "attempted_action": "deposit"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}
```

## Files Changed

### Core Implementation
- `app/components/UI/Predict/controllers/PredictController.ts`
- `app/components/UI/Predict/hooks/usePredictEligibility.ts`
- `app/components/UI/Predict/hooks/usePredictActionGuard.ts`
- `app/components/UI/Predict/constants/eventNames.ts`

### Components
-
`app/components/UI/Predict/components/PredictBalance/PredictBalance.tsx`
-
`app/components/UI/Predict/components/PredictAddFundsSheet/PredictAddFundsSheet.tsx`
-
`app/components/UI/Predict/views/PredictMarketDetails/PredictMarketDetails.tsx`
-
`app/components/UI/Predict/components/PredictPositionsHeader/PredictPositionsHeader.tsx`
-
`app/components/UI/Predict/components/PredictPositionDetail/PredictPositionDetail.tsx`
-
`app/components/UI/Predict/components/PredictMarketSingle/PredictMarketSingle.tsx`
-
`app/components/UI/Predict/components/PredictMarketOutcome/PredictMarketOutcome.tsx`
-
`app/components/UI/Predict/components/PredictMarketMultiple/PredictMarketMultiple.tsx`

### Tests
- `app/components/UI/Predict/controllers/PredictController.test.ts`
- `app/components/UI/Predict/hooks/usePredictEligibility.test.ts`
-
`app/components/UI/Predict/components/PredictAddFundsSheet/PredictAddFundsSheet.test.tsx`

## Testing Instructions

### Manual Testing

1. **Setup geoblock scenario:**
- Use VPN or modify geoblock API response to return `isEligible: false`

2. **Test each action:**
   - Try to deposit funds → Check analytics event sent
   - Try to place a prediction → Check analytics event sent
   - Try to cash out → Check analytics event sent
   - Try to claim winnings → Check analytics event sent

3. **Verify analytics:**
   - Open DevTools console
   - Look for `📊 [Analytics] PREDICT_GEO_BLOCKED_TRIGGERED` logs
   - Verify `country` and `attempted_action` are correct

### Automated Testing

```bash
# Run all Predict tests
yarn jest ./app/components/UI/Predict

# Run specific test suites
yarn jest app/components/UI/Predict/controllers/PredictController.test.ts
yarn jest app/components/UI/Predict/hooks/usePredictEligibility.test.ts
```

## Migration Notes

### State Migration

No migration required. The consolidated state structure is backward
compatible:
- Old state with empty `eligibility` object will work correctly
- `refreshEligibility()` will populate new structure on first call

### API Compatibility

No API changes required. The geoblock API response format remains the
same:
```typescript
interface GeoBlockResponse {
  isEligible: boolean;
  country?: string;
}
```

## Future Enhancements

1. **Enhanced Metrics:**
   - Add `ip` to analytics (currently stored but not tracked)
   - Track `region` for more granular insights

2. **User Education:**
   - Show country-specific messaging
   - Suggest alternative actions for blocked users

3. **Dashboard Integration:**
   - Real-time geoblock monitoring
   - Alerts for sudden spikes in blocked regions

## Checklist

- [x] State structure refactored and tested
- [x] Analytics event implemented
- [x] All guarded actions updated with `attemptedAction`
- [x] Tests updated and passing (67 suites, 1687 tests)
- [x] Dev logging added for debugging
- [x] Code follows project guidelines
- [x] No breaking changes

## Related Issues

- Tracking user geoblocking for compliance and UX insights
- Understanding geographic distribution of blocked actions


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Add geo-block analytics and migrate eligibility to include country,
wiring attemptedAction tracking across guarded Predict actions.
> 
> - **Analytics**:
> - Add `PREDICT_GEO_BLOCKED_TRIGGERED` event and properties `country`
and `attempted_action`.
> - **State/Controller**:
> - Change `PredictController.state.eligibility` to `{ [providerId]: {
eligible: boolean; country?: string } }`.
> - Update `refreshEligibility()` to store country; add
`trackGeoBlockTriggered()`.
> - **Providers**:
> - Update `PredictProvider.isEligible()` to return `{ isEligible,
country }` via `GeoBlockResponse`.
>   - Implement in `PolymarketProvider.isEligible()`.
> - **Hooks**:
> - `usePredictEligibility()` returns `{ isEligible, country }` (default
`false` when unset).
> - `usePredictActionGuard()` accepts `{ checkBalance, attemptedAction
}` and tracks geo-blocks when blocked.
> - **UI (guarded actions instrumented with `attemptedAction`)**:
>   - `PredictAddFundsSheet`, `PredictBalance` → deposit.
> - `PredictMarketDetails`, `PredictMarketSingle`,
`PredictMarketOutcome`, `PredictMarketMultiple` → predict/buy, claim.
> - `PredictPositionsHeader` → claim; `PredictPositionDetail` → cashout.
> - **MetaMetrics**:
>   - Register new event in `MetaMetrics.events`.
> - **Tests**:
> - Update controller, hooks, provider, and component tests for new
eligibility shape, geo-block tracking, and attemptedAction args.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e6d0566. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: andrepimenta

app/components/UI/Predict/components/PredictAddFundsSheet/PredictAddFundsSheet.test.tsx

@@ -372,6 +372,7 @@ describe('PredictAddFundsSheet', () => {
       expect(mockExecuteGuardedAction).toHaveBeenCalledTimes(1);
       expect(mockExecuteGuardedAction).toHaveBeenCalledWith(
         expect.any(Function),
+        { attemptedAction: 'deposit' },
       );
     });
 

app/components/UI/Predict/components/PredictAddFundsSheet/PredictAddFundsSheet.tsx

@@ -19,6 +19,7 @@ import { usePredictActionGuard } from '../../hooks/usePredictActionGuard';
 import { POLYMARKET_PROVIDER_ID } from '../../providers/polymarket/constants';
 import { NavigationProp, useNavigation } from '@react-navigation/native';
 import { PredictNavigationParamList } from '../../types/navigation';
+import { PredictEventValues } from '../../constants/eventNames';
 import {
   usePredictBottomSheet,
   type PredictBottomSheetRef,
@@ -50,9 +51,12 @@ const PredictAddFundsSheet = forwardRef<
   };
 
   const handleAddFunds = () => {
-    executeGuardedAction(() => {
-      deposit();
-    });
+    executeGuardedAction(
+      () => {
+        deposit();
+      },
+      { attemptedAction: PredictEventValues.ATTEMPTED_ACTION.DEPOSIT },
+    );
   };
 
   useImperativeHandle(ref, getRefHandlers, [getRefHandlers]);

app/components/UI/Predict/components/PredictBalance/PredictBalance.tsx

@@ -35,6 +35,7 @@ import { usePredictActionGuard } from '../../hooks/usePredictActionGuard';
 import { NavigationProp, useNavigation } from '@react-navigation/native';
 import { PredictNavigationParamList } from '../../types/navigation';
 import { usePredictWithdraw } from '../../hooks/usePredictWithdraw';
+import { PredictEventValues } from '../../constants/eventNames';
 
 // This is a temporary component that will be removed when the deposit flow is fully implemented
 interface PredictBalanceProps {
@@ -68,9 +69,12 @@ const PredictBalance: React.FC<PredictBalanceProps> = ({ onLayout }) => {
   }, [isDepositPending, loadBalance]);
 
   const handleAddFunds = useCallback(() => {
-    executeGuardedAction(() => {
-      deposit();
-    });
+    executeGuardedAction(
+      () => {
+        deposit();
+      },
+      { attemptedAction: PredictEventValues.ATTEMPTED_ACTION.DEPOSIT },
+    );
   }, [deposit, executeGuardedAction]);
 
   const handleWithdraw = useCallback(() => {

app/components/UI/Predict/components/PredictMarketMultiple/PredictMarketMultiple.test.tsx

@@ -8,6 +8,14 @@ import { PredictMarket, Recurrence } from '../../types';
 import { PredictEventValues } from '../../constants/eventNames';
 import Routes from '../../../../../constants/navigation/Routes';
 
+jest.mock('../../../../../core/Engine', () => ({
+  context: {
+    PredictController: {
+      trackGeoBlockTriggered: jest.fn(),
+    },
+  },
+}));
+
 const mockNavigate = jest.fn();
 jest.mock('@react-navigation/native', () => {
   const actualNav = jest.requireActual('@react-navigation/native');

app/components/UI/Predict/components/PredictMarketMultiple/PredictMarketMultiple.tsx

@@ -132,7 +132,10 @@ const PredictMarketMultiple: React.FC<PredictMarketMultipleProps> = ({
           },
         });
       },
-      { checkBalance: true },
+      {
+        checkBalance: true,
+        attemptedAction: PredictEventValues.ATTEMPTED_ACTION.PREDICT,
+      },
     );
   };
 

app/components/UI/Predict/components/PredictMarketOutcome/PredictMarketOutcome.test.tsx

@@ -10,6 +10,14 @@ import PredictMarketOutcome from '.';
 const mockAlert = jest.fn();
 jest.spyOn(Alert, 'alert').mockImplementation(mockAlert);
 
+jest.mock('../../../../../core/Engine', () => ({
+  context: {
+    PredictController: {
+      trackGeoBlockTriggered: jest.fn(),
+    },
+  },
+}));
+
 const mockNavigate = jest.fn();
 jest.mock('@react-navigation/native', () => {
   const actualNav = jest.requireActual('@react-navigation/native');

app/components/UI/Predict/components/PredictMarketOutcome/PredictMarketOutcome.tsx

@@ -96,7 +96,10 @@ const PredictMarketOutcome: React.FC<PredictMarketOutcomeProps> = ({
           },
         });
       },
-      { checkBalance: true },
+      {
+        checkBalance: true,
+        attemptedAction: PredictEventValues.ATTEMPTED_ACTION.PREDICT,
+      },
     );
   };
 

app/components/UI/Predict/components/PredictMarketSingle/PredictMarketSingle.test.tsx

@@ -16,6 +16,14 @@ import Routes from '../../../../../constants/navigation/Routes';
 const mockAlert = jest.fn();
 jest.spyOn(Alert, 'alert').mockImplementation(mockAlert);
 
+jest.mock('../../../../../core/Engine', () => ({
+  context: {
+    PredictController: {
+      trackGeoBlockTriggered: jest.fn(),
+    },
+  },
+}));
+
 // Mock navigation
 const mockNavigate = jest.fn();
 jest.mock('@react-navigation/native', () => ({

app/components/UI/Predict/components/PredictMarketSingle/PredictMarketSingle.tsx

@@ -176,7 +176,10 @@ const PredictMarketSingle: React.FC<PredictMarketSingleProps> = ({
           },
         });
       },
-      { checkBalance: true },
+      {
+        checkBalance: true,
+        attemptedAction: PredictEventValues.ATTEMPTED_ACTION.PREDICT,
+      },
     );
   };
 

app/components/UI/Predict/components/PredictPositionDetail/PredictPositionDetail.tsx

@@ -60,20 +60,23 @@ const PredictPosition: React.FC<PredictPositionProps> = ({
   )?.groupItemTitle;
 
   const onCashOut = () => {
-    executeGuardedAction(() => {
-      const _outcome = market?.outcomes.find(
-        (o) => o.id === position.outcomeId,
-      );
-      navigate(Routes.PREDICT.MODALS.ROOT, {
-        screen: Routes.PREDICT.MODALS.SELL_PREVIEW,
-        params: {
-          market,
-          position,
-          outcome: _outcome,
-          entryPoint: PredictEventValues.ENTRY_POINT.PREDICT_MARKET_DETAILS,
-        },
-      });
-    });
+    executeGuardedAction(
+      () => {
+        const _outcome = market?.outcomes.find(
+          (o) => o.id === position.outcomeId,
+        );
+        navigate(Routes.PREDICT.MODALS.ROOT, {
+          screen: Routes.PREDICT.MODALS.SELL_PREVIEW,
+          params: {
+            market,
+            position,
+            outcome: _outcome,
+            entryPoint: PredictEventValues.ENTRY_POINT.PREDICT_MARKET_DETAILS,
+          },
+        });
+      },
+      { attemptedAction: PredictEventValues.ATTEMPTED_ACTION.CASHOUT },
+    );
   };
 
   const renderValueText = () => {