Commit bc12958
authored
feat(perps): add deeplink support for perps (MetaMask#18568)
<!--
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**
This PR implements deeplink support for the Perps (perpetual futures)
feature, enabling direct navigation to Perps markets from external
sources like marketing campaigns, notifications, and social media.
The implementation supports two main deeplink types:
1. **Perps Market Overview**: Routes users to the main Perps tab (with
tutorial flow for first-time users)
2. **Specific Asset Details**: Routes users directly to a specific perps
asset (e.g., BTC, ETH)
## **Changelog**
CHANGELOG entry: Added deeplink support for Perps markets, allowing
direct navigation to Perps tab and specific asset details
## **Related issues**
Fixes: TAT-1344
## **Manual testing steps**
### Testing Deeplinks
#### iOS Testing
```bash
# Test Perps market overview deeplink
xcrun simctl openurl booted "https://link-test.metamask.io/perps"
# Test specific asset deeplinks
xcrun simctl openurl booted "https://link-test.metamask.io/perps-asset?symbol=BTC"
xcrun simctl openurl booted "https://link-test.metamask.io/perps-asset?symbol=ETH"
xcrun simctl openurl booted "https://link-test.metamask.io/perps-asset?symbol=SOL"
```
#### Android Testing
```bash
# Test Perps market overview deeplink
adb shell am start -W -a android.intent.action.VIEW -d "https://link-test.metamask.io/perps" io.metamask.debug
# Test specific asset deeplinks
adb shell am start -W -a android.intent.action.VIEW -d "https://link-test.metamask.io/perps-asset?symbol=BTC" io.metamask.debug
adb shell am start -W -a android.intent.action.VIEW -d "https://link-test.metamask.io/perps-asset?symbol=ETH" io.metamask.debug
```
https://github.com/user-attachments/assets/d391fca1-be2a-4d65-96b2-2c5f2ef2ae34
### Resetting First-Time User State
To test the tutorial flow for first-time users, you need to reset the
Perps state:
1. **Via Redux DevTools (Development builds):**
- Open the app with Redux DevTools enabled
- Navigate to Redux state
- Find `engine.backgroundState.PerpsController`
- Set `isFirstTimeUser: { testnet: true, mainnet: true }`
2. **Via Settings Menu:**
- Go to Settings → Advanced → Reset Account
- This will reset all account data including Perps state
### Test Scenarios
```gherkin
Feature: Perps Deeplinks Navigation
Scenario: First-time user navigates via perps deeplink
Given the user has MetaMask Mobile installed
And the user has never used Perps before (reset state if needed)
When user clicks on deeplink "https://link-test.metamask.io/perps"
Then the app opens to the Perps Tutorial screen
And after completing or skipping the tutorial, user sees the Perps tab selected
Scenario: Returning user navigates via perps deeplink
Given the user has MetaMask Mobile installed
And the user has completed the Perps tutorial
When user clicks on deeplink "https://link-test.metamask.io/perps"
Then the app opens directly to the Wallet home with Perps tab selected
Scenario: User navigates to specific BTC asset via deeplink
Given the user has MetaMask Mobile installed
When user clicks on deeplink "https://link-test.metamask.io/perps-asset?symbol=BTC"
Then the app opens directly to the BTC perps market details screen
Scenario: User navigates to specific ETH asset via deeplink
Given the user has MetaMask Mobile installed
When user clicks on deeplink "https://link-test.metamask.io/perps-asset?symbol=ETH"
Then the app opens directly to the ETH perps market details screen
Scenario: User navigates with invalid asset symbol
Given the user has MetaMask Mobile installed
When user clicks on deeplink "https://link-test.metamask.io/perps-asset?symbol=INVALID"
Then the app opens to the Perps tab (fallback behavior)
Scenario: Tutorial skip navigates correctly from deeplink
Given the user is a first-time Perps user
And the user arrived via deeplink
When user skips the tutorial
Then the app navigates to Wallet home with Perps tab selected
And the user can see the Perps markets list
```
### Expected Results
1. **First-time users**: Should see the tutorial carousel with 6 steps,
then navigate to Perps tab
2. **Returning users**: Should navigate directly to Wallet home with
Perps tab selected
3. **Asset deeplinks**: Should open the specific market details view
4. **Invalid symbols**: Should fallback to Perps markets list
5. **Tab selection**: The Perps tab should be visually selected and
active after navigation
## **Screenshots/Recordings**
### **Before**
- No deeplink support for Perps feature
- Users had to manually navigate to Perps tab through the app
### **After**
- Direct deeplink navigation to Perps markets
- Support for specific asset deeplinks (BTC, ETH, SOL, etc.)
- Smart routing based on user state (tutorial vs direct navigation)
https://github.com/user-attachments/assets/28b55198-995a-4e55-abc1-6715e528d9ac
## **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.1 parent 7e4b249 commit bc12958
19 files changed
Lines changed: 1442 additions & 225 deletions
File tree
- app
- components
- UI/Perps
- components/PerpsTutorialCarousel
- constants
- controllers
- hooks
- selectors/perpsController
- Views
- Settings/AdvancedSettings/ResetAccountModal
- Wallet
- constants
- core/DeeplinkManager
- Handlers
- ParseManager
Lines changed: 152 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
7 | 7 | | |
8 | 8 | | |
9 | 9 | | |
| 10 | + | |
10 | 11 | | |
11 | 12 | | |
12 | 13 | | |
| |||
51 | 52 | | |
52 | 53 | | |
53 | 54 | | |
| 55 | + | |
54 | 56 | | |
55 | 57 | | |
56 | 58 | | |
| |||
120 | 122 | | |
121 | 123 | | |
122 | 124 | | |
| 125 | + | |
123 | 126 | | |
124 | 127 | | |
125 | 128 | | |
126 | 129 | | |
| 130 | + | |
127 | 131 | | |
128 | 132 | | |
129 | 133 | | |
130 | 134 | | |
| 135 | + | |
131 | 136 | | |
132 | 137 | | |
133 | 138 | | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
134 | 144 | | |
135 | 145 | | |
136 | 146 | | |
| |||
226 | 236 | | |
227 | 237 | | |
228 | 238 | | |
229 | | - | |
230 | | - | |
231 | | - | |
| 239 | + | |
232 | 240 | | |
233 | 241 | | |
234 | 242 | | |
| |||
300 | 308 | | |
301 | 309 | | |
302 | 310 | | |
| 311 | + | |
| 312 | + | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
| 318 | + | |
| 319 | + | |
| 320 | + | |
| 321 | + | |
| 322 | + | |
| 323 | + | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
| 327 | + | |
| 328 | + | |
| 329 | + | |
| 330 | + | |
| 331 | + | |
| 332 | + | |
| 333 | + | |
| 334 | + | |
| 335 | + | |
| 336 | + | |
| 337 | + | |
| 338 | + | |
| 339 | + | |
| 340 | + | |
| 341 | + | |
| 342 | + | |
| 343 | + | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
| 347 | + | |
| 348 | + | |
| 349 | + | |
| 350 | + | |
| 351 | + | |
| 352 | + | |
| 353 | + | |
| 354 | + | |
| 355 | + | |
| 356 | + | |
| 357 | + | |
| 358 | + | |
| 359 | + | |
| 360 | + | |
| 361 | + | |
| 362 | + | |
| 363 | + | |
| 364 | + | |
| 365 | + | |
| 366 | + | |
| 367 | + | |
| 368 | + | |
| 369 | + | |
| 370 | + | |
| 371 | + | |
| 372 | + | |
| 373 | + | |
| 374 | + | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
| 380 | + | |
| 381 | + | |
| 382 | + | |
| 383 | + | |
| 384 | + | |
| 385 | + | |
| 386 | + | |
| 387 | + | |
| 388 | + | |
| 389 | + | |
| 390 | + | |
| 391 | + | |
| 392 | + | |
| 393 | + | |
| 394 | + | |
| 395 | + | |
| 396 | + | |
| 397 | + | |
| 398 | + | |
| 399 | + | |
| 400 | + | |
| 401 | + | |
| 402 | + | |
| 403 | + | |
| 404 | + | |
| 405 | + | |
| 406 | + | |
| 407 | + | |
| 408 | + | |
| 409 | + | |
| 410 | + | |
| 411 | + | |
| 412 | + | |
| 413 | + | |
| 414 | + | |
| 415 | + | |
| 416 | + | |
| 417 | + | |
| 418 | + | |
| 419 | + | |
| 420 | + | |
| 421 | + | |
| 422 | + | |
| 423 | + | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
| 437 | + | |
| 438 | + | |
| 439 | + | |
| 440 | + | |
| 441 | + | |
| 442 | + | |
| 443 | + | |
| 444 | + | |
| 445 | + | |
| 446 | + | |
| 447 | + | |
| 448 | + | |
| 449 | + | |
| 450 | + | |
303 | 451 | | |
Lines changed: 41 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | | - | |
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
2 | 7 | | |
3 | 8 | | |
4 | 9 | | |
| |||
25 | 30 | | |
26 | 31 | | |
27 | 32 | | |
| 33 | + | |
28 | 34 | | |
29 | 35 | | |
30 | 36 | | |
| |||
91 | 97 | | |
92 | 98 | | |
93 | 99 | | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
94 | 104 | | |
95 | 105 | | |
96 | 106 | | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
97 | 110 | | |
98 | 111 | | |
99 | 112 | | |
| |||
156 | 169 | | |
157 | 170 | | |
158 | 171 | | |
| 172 | + | |
| 173 | + | |
159 | 174 | | |
160 | 175 | | |
161 | 176 | | |
| |||
203 | 218 | | |
204 | 219 | | |
205 | 220 | | |
206 | | - | |
207 | | - | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
208 | 246 | | |
209 | 247 | | |
210 | 248 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
69 | 69 | | |
70 | 70 | | |
71 | 71 | | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
72 | 77 | | |
73 | 78 | | |
74 | 79 | | |
| |||
0 commit comments