fix: try fixing X deeplinks by adding $deeplink_path param [GE-139] cp-7.69.0

[baptiste-marchand]

Description

Fix branch deeplinks not working with the X (Twitter) app by adding a $deeplink_path param in branch.io and consuming it in MetaMask Mobile.

Context

• Platform: happens only on iOS. Android behaves differently (no Deepview in our flow).
• User taps a t.co link in X (Twitter) → redirects to https://metamask.app.link/1WkF6GmE40b (which is a link generated by X/Branch.io on Tweet posting) → Branch Deepview is shown → user taps “Get the app” → opens MetaMask via Universal Link: https://metamask-alternate.app.link/1WkF6GmE40b?__branch_flow_type=viewapp&__branch_flow_id=...&__branch_mobile_deepview_type=1.
• Issue: The app opens correctly, but in-app we show a “page not found” (404). So the OS and Branch open the app, but we don’t know which in-app route corresponds to link ID 1WkF6GmE40b.

What we found

1. No resolved URI from the SDK

• The Branch iOS SDK (and react-native-branch) give us:
  • The raw URL that opened the app (e.g. https://metamask-alternate.app.link/1WkF6GmE40b?...), and
  • The params from the session (e.g. from getLatestReferringParams() / subscribe callback).
• The SDK does not build a custom deeplink URI (e.g. metamask://swap) from link data; it only returns the params. So we have to do routing ourselves.

2. Implemented fix:

• Added a $deeplink_path in Branch deeplinks (this must be added to every existing and future deeplinks that we want to post on X)
• Read it from the params and build our deeplink ourselves (e.g. metamask://${params.$deeplink_path}) and then route inside the app.

Changelog

CHANGELOG entry: Fixed a bug that was causing deeplinks opened from X app to fail

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/GE-139
Fixes: #27140

Manual testing steps

Feature: my feature name

  Scenario: user [verb for user action]
    Given [describe expected initial app state]

    When user [verb for user action]
    Then [describe expected outcome]

Screenshots/Recordings

Before

After

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). 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.

---

Note

Medium Risk
Touches deeplink routing/host allowlists and Branch handling on app start, which can affect navigation from external links, but the change is narrowly scoped and covered by new unit tests.

Overview
Fixes Branch short-link universal links (notably from X on iOS) by introducing rewriteBranchUri, which converts metamask-alternate.app.link/<id> URLs into https://link.metamask.io/<$deeplink_path> while preserving query params.

DeeplinkManager.start() now applies this rewrite for both cold-start Branch params (~referring_link) and branch.subscribe events, replacing the prior getLatestReferringParams fallback logic.

Adds MM_UNIVERSAL_LINK_HOST_ALTERNATE (metamask-alternate.app.link) and includes it in universal-link host validation (handleUniversalLink) and MetaMask-host detection (util/deeplinks), with new tests covering rewrite and routing behavior.

^{Written by Cursor Bugbot for commit de4e3dc. This will update automatically on new commits. Configure here.}

[github-actions]

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.

[Montoya]

This fixes #27140

[Cal-L]

LGTM

[cursor]

Cold start incorrectly processes unrewritten ~referring_link URI

High Severity

rewriteBranchUri returns the original uri (truthy) when rewriting conditions aren't met (e.g., +clicked_branch_link is false or $deeplink_path is absent). The cold start caller checks if (rewritten) as a gate, so any truthy ~referring_link bypasses the +non_branch_link fallback. This causes the app to process a raw, unresolvable Branch short link (leading to a 404) or a stale ~referring_link from a prior session. The function needs to return undefined instead of uri when it doesn't actually rewrite.

Additional Locations (1)

• app/core/DeeplinkManager/DeeplinkManager.ts#L92-L100

 

[Cal-L]

Code looks good. Let's revert the version changes

[cursor]

Cursor Bugbot has reviewed your changes 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.}

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeTrade, SmokeConfirmations, SmokeRamps
• Selected Performance tags: None (no tests recommended)
• Risk Level: medium
• AI Confidence: 78%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR modifies deep link handling in DeeplinkManager, adds rewrite logic for Branch short links, and expands supported universal link hosts (metamask-alternate.app.link). Deep links are critical entry points into in-app flows, especially swap and buy flows that are commonly triggered via Branch/universal links.

Key impacts:

• Rewrites Branch short links using $deeplink_path to link.metamask.io/ while preserving query params.
• Alters cold start behavior for Branch links (getLatestReferringParams flow).
• Changes subscribe callback handling to use rewritten URI.
• Expands supported universal link domains.

These changes can directly affect:

• Swap deep links (e.g., /swap with amount/token params) → SmokeTrade.
• Any flow that results in transaction confirmations from deep links (swap/bridge) → SmokeConfirmations (required when selecting SmokeTrade).
• Buy/on-ramp deep links triggered via universal links → SmokeRamps (explicitly covers deep link navigation into buy flows).

No changes affect controllers, Engine, account management, network management, Snaps, or multi-chain provider logic. Therefore, broader tags like SmokeWalletPlatform, SmokeAccounts, SmokeNetworkAbstractions, etc., are not required.

Given the centrality of deep links to growth and transaction flows, this is medium risk: incorrect rewriting could silently break swap or buy entry points. Running the focused trade + confirmations + ramps suites provides strong coverage with minimal over-testing.

Performance Test Selection:
Changes are limited to deep link parsing and URI rewriting logic. No UI rendering, state management, controller initialization, or performance-sensitive flows (startup timing, account list, swaps execution performance) were modified. Therefore, no performance tests are required.

View GitHub Actions results

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
11 value mismatches detected (expected — fixture represents an existing user).
View details

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
86.2% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud