Repository navigation
fix(onboarding): resume direct deep-link destinations - #47678
Conversation
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
✨ Files requiring CODEOWNER review ✨🕵️ @MetaMask/extension-privacy-reviewers (1 files, +1 -0)
🧪 @MetaMask/qa (1 files, +1 -0)
🔐 @MetaMask/web3auth (4 files, +350 -95)
|
Builds ready [582c814]
⚡ Performance Benchmarks (Total: 🟢 9 pass · 🟡 0 warn · 🔴 4 fail)
Bundle Size Diffs [🚀 Bundle size reduced!]
|
Builds ready [8c130a8]
⚡ Performance Benchmarks (Total: 🟢 8 pass · 🟡 2 warn · 🔴 3 fail)
Bundle Size Diffs [🚨 Warning! Bundle size has increased!]
|
Keep deferred attribution tracking while resuming the latest saved destination in the current UI session. Avoid opening a side panel for the direct route. Security approval: the requester identified themselves as the Extension Security team and approved superseding a pending deferred interstitial in the implementation conversation.
Builds ready [843dbd2]
⚡ Performance Benchmarks (Total: 🟢 9 pass · 🟡 2 warn · 🔴 2 fail)
Bundle Size Diffs [🚨 Warning! Bundle size has increased!]
|
Builds ready [2088d58] [reused from 843dbd2]
⚡ Performance Benchmarks (Total: 🟢 9 pass · 🟡 2 warn · 🔴 2 fail)
Bundle Size Diffs [🚨 Warning! Bundle size has increased!]
|
This reverts commit ac899f3 to keep this PR focused on deep-link onboarding.
Builds ready [bfbb913] [reused from ac899f3]
⚡ Performance Benchmarks (Total: 🟢 5 pass · 🟡 2 warn · 🔴 1 fail)
Bundle Size Diffs [🚨 Warning! Bundle size has increased!]
|
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 0cb6cb4. Configure here.
Builds ready [0cb6cb4]
⚡ Performance Benchmarks (Total: 🟢 6 pass · 🟡 4 warn · 🔴 3 fail)
Bundle Size Diffs [🚨 Warning! Bundle size has increased!]
|
There was a problem hiding this comment.
🟡 Changes recommended
An onboarding-completion failure redirects to Home and clears the saved direct destination, so retrying setup loses the intended direct link.
1 open issue
What changed in this PR
This PR preserves direct internal deep-link destinations through onboarding, addressing #47667 without depending on referral functionality.
Changes:
- Saves and restores the destination, including query parameters and fragments, within the receiving UI session.
- Prioritizes saved direct destinations over deferred navigation while retaining install attribution and deferred-link metrics.
- Allows validly signed direct links to skip the interstitial when onboarding is explicitly incomplete, with regression coverage.
| File | Description |
|---|---|
ui/store/actionConstants.ts |
Adds the onboarding redirect action constant. |
ui/pages/onboarding-flow/onboarding-flow.tsx |
Restores saved destinations after onboarding and social import. |
ui/pages/onboarding-flow/onboarding-flow.test.tsx |
Covers destination restoration and clearing. |
ui/pages/onboarding-flow/hooks/useOnboardingCompletion.ts |
Applies direct-link precedence and keeps navigation in the receiving UI. |
ui/pages/onboarding-flow/hooks/useOnboardingCompletion.test.ts |
Tests precedence, attribution, side-panel behavior, and retries. |
ui/layouts/require-authenticated.tsx |
Captures protected destinations before redirecting to onboarding. |
ui/layouts/require-authenticated.test.tsx |
Tests route preservation and destination replacement. |
ui/ducks/app/app.ts |
Adds session-local redirect state, action, and selector. |
ui/ducks/app/app.test.js |
Tests redirect updates and clearing. |
test/e2e/tests/settings/state-logs.json |
Updates the expected UI state shape. |
test/e2e/tests/metrics/state-snapshots/errors-after-init-opt-in-ui-state.json |
Includes redirect state in the metrics snapshot. |
shared/lib/deep-links/security-policy.ts |
Adds the valid-signature pre-onboarding exception. |
shared/lib/deep-links/security-policy.test.ts |
Tests signature and onboarding-state policy combinations. |
app/scripts/lib/deep-links/deep-link.router.test.ts |
Covers signed direct-link routing across onboarding states. |
app/scripts/lib/deep-links/deep-link-router.ts |
Supplies cached onboarding state to the security policy. |
Review effort: Balanced
Builds ready [c153a3b]
⚡ Performance Benchmarks (Total: 🟢 9 pass · 🟡 1 warn · 🔴 3 fail)
Bundle Size Diffs [🚨 Warning! Bundle size has increased!]
|
|
| source: 'intercepted', | ||
| signatureStatus: parsed.signature, | ||
| requestOrigin, | ||
| getCompletedOnboarding: () => getState().completedOnboarding, |
There was a problem hiding this comment.
Before onboarding, a signed link to buy, card, onboarding, sell or top-traders skips the interstitial and opens its external page directly, with no onboarding in between to stand in for it.
Maybe we should leave redirect routes out of the pre-onboarding skip?
diff --git a/app/scripts/lib/deep-links/deep-link-router.ts b/app/scripts/lib/deep-links/deep-link-router.ts
--- a/app/scripts/lib/deep-links/deep-link-router.ts
+++ b/app/scripts/lib/deep-links/deep-link-router.ts
@@ -190,7 +190,10 @@ export class DeepLinkRouter extends EventEmitter<{
source: 'intercepted',
signatureStatus: parsed.signature,
requestOrigin,
- getCompletedOnboarding: () => getState().completedOnboarding,
+ getCompletedOnboarding:
+ 'redirectTo' in parsed.destination
+ ? undefined
+ : () => getState().completedOnboarding,
getSkipDeepLinkInterstitial: () =>
Boolean(getState().preferences?.skipDeepLinkInterstitial),
});
diff --git a/app/scripts/lib/deep-links/deep-link.router.test.ts b/app/scripts/lib/deep-links/deep-link.router.test.ts
--- a/app/scripts/lib/deep-links/deep-link.router.test.ts
+++ b/app/scripts/lib/deep-links/deep-link.router.test.ts
@@ -545,6 +545,31 @@ describe('DeepLinkRouter', () => {
});
});
+ it('shows the interstitial for signed redirecting routes before onboarding', async function () {
+ getState.mockReturnValueOnce({
+ completedOnboarding: false,
+ preferences: { skipDeepLinkInterstitial: false },
+ } as unknown as ReturnType<MetaMaskController['getState']>);
+ parseMock.mockResolvedValue({
+ signature: 'valid',
+ route: {
+ pathname: '/buy',
+ },
+ destination: {
+ redirectTo: new URL('https://example.com/internal-route'),
+ },
+ } as ParsedDeepLink);
+
+ await onBeforeRequest?.({
+ tabId: 1,
+ url: 'https://example.com/buy',
+ } as browser.WebRequest.OnBeforeRequestDetailsType);
+
+ expect(browser.tabs.update).toHaveBeenCalledWith(1, {
+ url: 'chrome-extension://extension-id/home.html#link?u=%2Fbuy',
+ });
+ });
+
describe('resolveRequestOrigin', () => {
it('prefers initiator over originUrl', () => {
expect(There was a problem hiding this comment.
I don't know. I don't think there is a good security reason to do it. And I don't know if there is a good UX reason to do it (or not do it).
There was a problem hiding this comment.
Don't have a strong reason other than keeping the interstitial's friction before onboarding, since a new user hasn't had the chance to turn it off. But in any case guess this is more of a nit, maybe for a follow-up where the interstitial prompts onboarding for redirect routes.
There was a problem hiding this comment.
I think we need a redesign of how deferred deep links (and the deep links handled by this PR) are presented to the user after onboarding completed. its kind of silly right now. it works, but its quite jarring!





Description
Opening an internal deep link before wallet onboarding is complete loses the intended destination and finishes on Home. Retain the internal route in the existing UI state before redirecting to onboarding, then resume and clear it when setup finishes.
The latest saved direct destination in the current UI session takes precedence over the install-time deferred destination. Preserve its query and fragment, and keep it in that UI when the side panel is enabled. No cross-tab synchronization is added. The social-import unlock path also retains its saved direct destination.
Keep install attribution and the deferred
DeepLinkUsedevent, including attribution and campaign parameters, even when a later direct link supplies the action. Without a saved direct destination, deferred navigation and its required interstitial remain the fallback. A saved direct destination also supersedes a pending deferred interstitial; the requester identified themselves as the Extension Security team and approved this behavior in the implementation conversation.Validly signed direct links also skip the interstitial while local onboarding state is explicitly incomplete, matching the existing behavior for signed deferred links. Unsigned or invalidly signed links and links received after onboarding retain the existing policy. The requester identified themselves as a member of Extension Security and explicitly approved this pre-onboarding exception in the implementation conversation, clarifying that it applies only to valid signatures in both flows.
Validation: 94 tests passed across five onboarding, routing, and unlock suites; full TypeScript checking, changed-file lint, and circular dependency checks passed. Both social-import completion-failure regression cases failed before the retry fix and passed afterward; automatic completion retry is also covered. Earlier signed-link onboarding regressions remain covered. Manual testing is pending.
Changelog
CHANGELOG entry: Fixed direct deep-link destinations being lost during onboarding and removed the extra pre-onboarding warning for validly signed links.
Related issues
Fixes #47667
Jira: MWPE-805
Related: #47665. This fix does not depend on referral functionality.
Manual testing steps
In a fresh extension profile, leave onboarding incomplete and open
https://link.metamask.io/privacy. Continue through the existing security warning, then finish wallet setup. Verify Privacy & Security opens at the MetaMetrics section instead of Home.Start with an install-time deferred link containing attribution and campaign parameters. Before finishing onboarding, open a different direct destination in the same UI. Complete setup and verify the later destination opens. With metrics enabled, verify install attribution and the deferred
DeepLinkUsedevent retain the original link's attribution and campaign parameters.Repeat with a deferred link that would require an interstitial. Verify the later direct destination supersedes that deferred action, and the direct link's own security warning still appears when required.
Repeat with the side-panel experience enabled. Verify the later destination opens in the UI that received it. Ordinary onboarding without a direct destination keeps its usual side-panel behavior.
Repeat through social import, including unlock/rehydration, and verify the saved direct destination is retained. For a supported link with product parameters, verify its query and scroll fragment survive setup.
Open another direct destination in the same UI before completion and verify the last one is used. Completing onboarding in a separate UI does not inherit that destination. If completion fails, retry and verify the destination remains available.
Repeat the install-attribution deferred-link flow without a later direct destination. Verify its destination and any required security warning remain the fallback.
With the interstitial opt-out disabled, open a validly signed direct link before onboarding is complete. Verify setup opens without a security warning and resumes the destination afterward. Repeat after onboarding and verify the normal warning appears. Repeat with unsigned and invalidly signed links before onboarding and verify the existing warning behavior remains.
Screenshots/Recordings
Not captured locally.
Pre-merge author checklist
Pre-merge reviewer checklist
Note
Medium Risk
Changes onboarding navigation, deep-link interstitial policy, and security-boundary logic for signed links before onboarding completes; mistakes could mis-route users or weaken warnings.
Overview
Fixes direct deep links being dropped when the wallet is still onboarding by introducing session-scoped
onboardingRedirectUI state.RequireAuthenticatedsaves the full internal path (query/hash) before sending users to onboarding; completion paths inuseOnboardingCompletion,onboarding-flow, and unlock/social-import flows resume that route and clear it, with the saved direct destination beating install-time deferred deep links while still emitting deferred DeepLinkUsed attribution.The deep-link security policy now consults
completedOnboarding: valid signed intercepted links skip the interstitial only while onboarding is explicitly incomplete; unsigned/invalid links and post-onboarding behavior stay unchanged. The router lazily reads controller state once per intercept for this check.Reviewed by Cursor Bugbot for commit c153a3b. Bugbot is set up for automated code reviews on this repo. Configure here.