Repository navigation
Commit 6870129
feat(rewards): open referral invites from deep links (#47665)
## **Description**
Open the existing referral invite sheet over the intended destination
when an internal deep link includes a single valid `ref`. This also
handles deferred links after onboarding, while preserving the sheet's
existing eligibility checks and interaction events.
Carry the code in a temporary document query parameter, then move it
into UI state before any routed screen mounts. Continue links remain
ordinary anchors, so opening a new tab and copying the URL still work.
Signed route parameters and security interstitial decisions keep their
existing behavior.
Share referral-code validation with the invite input and include
`referral_code` as a regular property on **Deep Link Used**.
Validation after updating main:
- 161 tests passed across 11 focused suites.
- CI follow-up: both RootLayout tests and all four dedicated
ReferralInvite tests pass after isolating the invite in the layout
fixture. The two layout failures were reproduced before the fix.
- Changed-file lint, full TypeScript checking, JSON fixture formatting,
and circular dependency checks passed.
- Resolved the root-layout merge conflict and updated the state-log
fixture for `pendingReferralCode`.
- Existing visual captures are below. Live-service and
install/onboarding verification remain pending.
## **Changelog**
CHANGELOG entry: Added referral invitations to deep links, including
links restored after onboarding.
## **Related issues**
Related: #47622
## **Manual testing steps**
1. Enable Basic Functionality and the Money rewards feature flag. Using
an eligible test wallet and a valid test referral code, open
`https://link.metamask.io/money?ref=CODE`. Complete any interstitial or
unlock step. Verify the intended screen appears with the invite
prefilled and the temporary document-level `ref` disappears from the
URL.
2. From an interstitial, open Continue in a new tab and copy/paste its
URL into another tab. Verify both preserve the invite code and
destination.
3. Decline or dismiss the invite and verify the destination remains
usable. Repeat and accept a valid offer. Check **Rewards Money Referral
Offer Interacted** events across both screens and **Deep Link Used**
with a regular `referral_code` property.
4. Repeat with an already-joined or ineligible wallet and verify the
existing eligibility checks skip the invite. Verify malformed or
duplicate `ref` values do not open it.
5. Follow a referral deep link through install and onboarding. Verify
the invite appears over the intended destination after onboarding,
unlock, and any interstitial. Verify it does not appear on those
prerequisite screens.
## **Screenshots/Recordings**
Captured using `yarn mm` and an isolated test wallet. This PR's captures
use `013e6a0`; the explicitly labeled after-comparison uses `7fe9521`
from #47682. Referral responses, eligibility/region state, and offer
copy are mocked; cashback rates and dates are illustrative. These
captures demonstrate the home and Money destination UI flows, not live
backend registration or install/onboarding. The standalone Money-page
referral recording uses a returning-user state with the Money
introduction already dismissed. The comparison below instead shows a
first Money visit with both dialogs opening together.
### Recordings
#### First-visit sheet-priority comparison
**Known limitation in this PR.** When the Money introduction and
referral invite open together, their ordering can depend on mount timing
and dismissal events can reach both dialogs. The fix is separate in the
stacked #47682; the after-recording is comparison evidence, not behavior
included in this PR.
**Before: this PR, #47665 (`013e6a0`).** On a first Money visit, both
dialogs mount. In this recording, the Money introduction covers the
referral invite, and pressing Escape dismisses both dialogs instead of
just the top one.
https://github.com/user-attachments/assets/33e5b755-b699-4c26-a4ee-2fa91d4d14c6
**After: companion #47682 (`7fe9521`).** In the same first-visit
scenario, the referral stays above the Money introduction and keeps
code-input focus. Escape closes only the referral; the Money
introduction remains open until separately dismissed.
https://github.com/user-attachments/assets/7e7eabbb-ce32-4be9-9842-ad9c89616865
#### Referral flows in this PR
**Money-page referral flow (returning user).** Follow
`/money?ref=DEMO2026` through the security interstitial, review the
prefilled invite over Money, accept it, and close the confirmation to
remain on the Money page.
https://github.com/user-attachments/assets/ed28c748-b36f-4596-a525-39ca30056027
**Accept an invite.** Continue past the security interstitial, review
the prefilled referral code, accept the invite, and close the cashback
confirmation to return to the destination.
https://github.com/user-attachments/assets/c5b1b691-d30f-4f6b-a394-7c83b500c6b6
**Validation and rate-limit feedback.** Enter a rejected code, correct
it, encounter a mocked rate-limit response, and choose Not now to return
to the destination.
https://github.com/user-attachments/assets/c84fe409-49e1-4342-be0c-2157ea74b4d5
**Dismiss an invite.** Close the invite without accepting it; the
destination remains available.
https://github.com/user-attachments/assets/8a1634d1-9b82-4353-a506-75a42b1fe32b
### Screenshots
<details open>
<summary>Open and accept an invite</summary>
**Security interstitial.** The unsigned referral link still shows the
third-party warning before Continue.
<img width="1280" height="800" alt="Security interstitial with the
third-party warning and Continue link"
src="https://github.com/user-attachments/assets/bd42524b-b655-4674-930b-1e9da0e72f37"
/>
**Prefilled invite.** The referral code is carried to the home
destination and prefilled in the invite sheet.
<img width="1280" height="800" alt="Referral invite sheet over the home
destination with DEMO2026 prefilled"
src="https://github.com/user-attachments/assets/83483188-75ff-4fca-af3d-a4e3fe5f445b"
/>
**Acceptance confirmation.** A successful mocked registration opens the
cashback-activated confirmation with sample offer dates.
<img width="1280" height="800" alt="Cashback activation confirmation
after accepting the test referral invite"
src="https://github.com/user-attachments/assets/354abd03-0fc4-43a3-ae4e-e18a9508b3aa"
/>
**Destination after acceptance.** Closing the confirmation leaves the
home screen usable without the invite.
<img width="1280" height="800" alt="Home destination after closing the
referral acceptance confirmation"
src="https://github.com/user-attachments/assets/2fbe1f40-eb45-4e99-8e6f-e48f14435e69"
/>
</details>
<details>
<summary>Code validation and rate limiting</summary>
**Rejected referral code.** An invalid-code response shows inline
feedback and disables Accept invite.
<img width="1280" height="800" alt="Referral invite with invalid-code
feedback and Accept invite disabled"
src="https://github.com/user-attachments/assets/43b60531-493b-4c03-b449-1b41ec40b9b0"
/>
**Corrected referral code.** Replacing the rejected code with a valid
one clears the error and enables Accept invite again.
<img width="1280" height="800" alt="Corrected referral code with the
error cleared and Accept invite enabled"
src="https://github.com/user-attachments/assets/fdd1c042-86fe-424a-acd0-cf38ce71fdd0"
/>
**Rate-limited acceptance.** A mocked HTTP 429 response shows retry
feedback and temporarily disables acceptance.
<img width="1280" height="800" alt="Referral invite showing rate-limit
feedback with acceptance temporarily disabled"
src="https://github.com/user-attachments/assets/c20dbafc-479b-4ad7-9e07-7695b8bc918f"
/>
</details>
<details>
<summary>Decline or dismiss without blocking the destination</summary>
**Decline with Not now.** Declining closes the invite and returns to the
existing destination.
<img width="1280" height="800" alt="Home destination after declining the
referral invite with Not now"
src="https://github.com/user-attachments/assets/c17e63ea-f212-42bb-a9d8-b6d144550fed"
/>
**Before dismissal.** The invite remains dismissible through its close
button.
<img width="1280" height="800" alt="Open referral invite before
dismissal with its close button available"
src="https://github.com/user-attachments/assets/43160f02-dc0a-4053-bef1-a3407c39a592"
/>
**After dismissal.** Closing the invite leaves the home screen
unobstructed and usable.
<img width="1280" height="800" alt="Unobstructed home destination after
dismissing the referral invite"
src="https://github.com/user-attachments/assets/6db4c740-2131-4418-8fb6-74d7c3a76c34"
/>
</details>
<details>
<summary>Conditions that skip the invite</summary>
**Already joined.** A mocked profile with the REFEREE role skips the
invite and keeps the destination visible.
<img width="1280" height="800" alt="Home destination without an invite
for an already-joined test profile"
src="https://github.com/user-attachments/assets/6564c670-b85e-4201-9b77-af30205fd541"
/>
**Restricted region.** A mocked excluded-country state skips the invite
rather than blocking the destination.
<img width="1280" height="800" alt="Home destination without an invite
for a restricted-region test profile"
src="https://github.com/user-attachments/assets/67f5a1af-72f4-4ef3-9e0d-18397b09b6d3"
/>
**Malformed referral parameter.** A link containing `ref=bad!` reaches
the destination without opening an invite.
<img width="1280" height="800" alt="Home destination without an invite
after a link containing a malformed referral code"
src="https://github.com/user-attachments/assets/10737fa0-d403-4618-a56d-91e4ba0e7ee3"
/>
</details>
<!--
### **Before**
### **After**
-->
## **Pre-merge author checklist**
- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask
Extension Coding
Standards](https://github.com/MetaMask/metamask-extension/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-extension/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**
> Changes deep-link routing, startup URL handling, and onboarding
completion navigation; security interstitial rules are preserved but
referral metadata now flows through those paths.
>
> **Overview**
> Adds end-to-end support for **Money referral codes** on internal deep
links via a validated `ref` query param.
>
> **Deep links** normalize and attach `ref` with `withReferralCode` on
direct extension destinations (router and interstitial Continue links)
while keeping existing interstitial/security behavior. **Deep Link
Used** analytics gain `referral_code`; malformed or duplicate `ref`
values are dropped.
>
> **UI startup** reads the temporary document `?ref=`, stores it as
`pendingReferralCode` in Redux (`consumeReferralCode` on boot), and
**`ReferralInvite`** in root layout opens the existing
**AcceptInviteSheet** over the destination when rewards are enabled.
Deferred links after onboarding set the same pending code. Referral
input normalization moves to shared `money-referral-code` helpers.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
9c5f618. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Baptiste Marchand <75846779+baptiste-marchand@users.noreply.github.com>1 parent b469544 commit 6870129
24 files changed
Lines changed: 445 additions & 39 deletions
File tree
- app/scripts/lib/deep-links
- test/e2e/tests/settings
- ui
- components/app/rewards/money-referral
- ducks/rewards-money
- helpers/utils
- hooks/rewards
- layouts
- pages
- deep-link
- onboarding-flow/hooks
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
| 4 | + | |
4 | 5 | | |
5 | 6 | | |
6 | 7 | | |
| |||
211 | 212 | | |
212 | 213 | | |
213 | 214 | | |
| 215 | + | |
214 | 216 | | |
215 | 217 | | |
216 | 218 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
122 | 122 | | |
123 | 123 | | |
124 | 124 | | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
125 | 159 | | |
126 | 160 | | |
127 | 161 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
32 | 41 | | |
33 | 42 | | |
34 | 43 | | |
| |||
127 | 136 | | |
128 | 137 | | |
129 | 138 | | |
130 | | - | |
| 139 | + | |
131 | 140 | | |
132 | | - | |
| 141 | + | |
133 | 142 | | |
134 | 143 | | |
135 | 144 | | |
136 | 145 | | |
137 | 146 | | |
138 | 147 | | |
| 148 | + | |
139 | 149 | | |
140 | 150 | | |
141 | 151 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
1 | 2 | | |
2 | 3 | | |
3 | 4 | | |
| |||
15 | 16 | | |
16 | 17 | | |
17 | 18 | | |
| 19 | + | |
| 20 | + | |
18 | 21 | | |
19 | 22 | | |
20 | 23 | | |
| |||
41 | 44 | | |
42 | 45 | | |
43 | 46 | | |
44 | | - | |
45 | | - | |
| 47 | + | |
46 | 48 | | |
47 | 49 | | |
48 | 50 | | |
| |||
53 | 55 | | |
54 | 56 | | |
55 | 57 | | |
| 58 | + | |
| 59 | + | |
56 | 60 | | |
57 | 61 | | |
58 | 62 | | |
59 | 63 | | |
60 | | - | |
61 | | - | |
62 | | - | |
| 64 | + | |
| 65 | + | |
63 | 66 | | |
64 | 67 | | |
65 | 68 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1374 | 1374 | | |
1375 | 1375 | | |
1376 | 1376 | | |
| 1377 | + | |
1377 | 1378 | | |
1378 | 1379 | | |
1379 | 1380 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
22 | 22 | | |
23 | 23 | | |
24 | 24 | | |
| 25 | + | |
25 | 26 | | |
26 | 27 | | |
27 | 28 | | |
| |||
49 | 50 | | |
50 | 51 | | |
51 | 52 | | |
52 | | - | |
53 | | - | |
54 | 53 | | |
55 | 54 | | |
56 | 55 | | |
| |||
88 | 87 | | |
89 | 88 | | |
90 | 89 | | |
91 | | - | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | | - | |
98 | | - | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | 90 | | |
105 | 91 | | |
106 | 92 | | |
| |||
0 commit comments