fix: try fixing X deeplinks by adding [GE-139] cp-7.69.0 (MetaMask#27139)

baptiste-marchand · web-flow · commit 06961042ca4b · 2026-03-10T23:06:29.000Z
## **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: MetaMask#27140 ## **Manual testing steps** ```gherkin 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](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile Coding Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md). - [ ] 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](https://jsdoc.app/) format if applicable - [ ] 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.  --- > [!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. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit de4e3dc. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>
diff --git a/app/core/AppConstants.ts b/app/core/AppConstants.ts
@@ -95,6 +95,7 @@ export default {
     },
   },
   MM_UNIVERSAL_LINK_HOST: 'metamask.app.link',
+  MM_UNIVERSAL_LINK_HOST_ALTERNATE: 'metamask-alternate.app.link',
   MM_IO_UNIVERSAL_LINK_HOST: 'link.metamask.io',
   MM_IO_UNIVERSAL_LINK_TEST_HOST: 'link-test.metamask.io',
   MM_DEEP_ITMS_APP_LINK: 'https://metamask.app.link/skAH3BaF99',
diff --git a/app/core/DeeplinkManager/DeeplinkManager.test.ts b/app/core/DeeplinkManager/DeeplinkManager.test.ts
@@ -2,7 +2,11 @@ import { NavigationProp, ParamListBase } from '@react-navigation/native';
 import { waitFor } from '@testing-library/react-native';
 import FCMService from '../../util/notifications/services/FCMService';
 import NavigationService from '../NavigationService';
-import SharedDeeplinkManager, { DeeplinkManager } from './DeeplinkManager';
+import SharedDeeplinkManager, {
+  DeeplinkManager,
+  rewriteBranchUri,
+} from './DeeplinkManager';
+import type { BranchParams } from './types/deepLinkAnalytics.types';
 import { handleDeeplink } from './handlers/legacy/handleDeeplink';
 import switchNetwork from '../../util/networks/switchNetwork';
 import parseDeeplink from './utils/parseDeeplink';
@@ -282,6 +286,34 @@ describe('SharedDeeplinkManager', () => {
   });
 });
 
+describe('rewriteBranchUri', () => {
+  it('rewrites host and path to link.metamask.io and preserves query when +clicked_branch_link and $deeplink_path are set', () => {
+    const uri =
+      'https://metamask-alternate.app.link/1WkF6GmE40b?amount=100&from=0x';
+    const params: BranchParams = {
+      '+clicked_branch_link': true,
+      $deeplink_path: 'swap',
+    };
+    expect(rewriteBranchUri(uri, params)).toBe(
+      'https://link.metamask.io/swap?amount=100&from=0x',
+    );
+  });
+
+  it('returns uri unchanged when +clicked_branch_link is false', () => {
+    const uri = 'https://metamask.app.link/swap';
+    expect(
+      rewriteBranchUri(uri, { '+clicked_branch_link': false } as BranchParams),
+    ).toBe(uri);
+  });
+
+  it('returns uri unchanged when $deeplink_path is missing', () => {
+    const uri = 'https://metamask.app.link/swap';
+    expect(
+      rewriteBranchUri(uri, { '+clicked_branch_link': true } as BranchParams),
+    ).toBe(uri);
+  });
+});
+
 describe('DeeplinkManager.start Branch deeplink handling', () => {
   beforeEach(() => {
     jest.clearAllMocks();
@@ -304,6 +336,31 @@ describe('DeeplinkManager.start Branch deeplink handling', () => {
     expect(handleDeeplink).toHaveBeenCalledWith({ uri: mockDeeplink });
   });
 
+  it('rewrites cold start Branch link using $deeplink_path from getLatestReferringParams', async () => {
+    (branch.getLatestReferringParams as jest.Mock).mockResolvedValue({
+      '+clicked_branch_link': true,
+      $deeplink_path: 'swap',
+      '~referring_link':
+        'https://metamask-alternate.app.link/1WkF6GmE40b?amount=500',
+    });
+    DeeplinkManager.start();
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(handleDeeplink).toHaveBeenCalledWith({
+      uri: 'https://link.metamask.io/swap?amount=500',
+    });
+  });
+
+  it('falls back to +non_branch_link on cold start when +clicked_branch_link is false', async () => {
+    const mockDeeplink = 'https://link.metamask.io/home';
+    (branch.getLatestReferringParams as jest.Mock).mockResolvedValue({
+      '+clicked_branch_link': false,
+      '+non_branch_link': mockDeeplink,
+    });
+    DeeplinkManager.start();
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(handleDeeplink).toHaveBeenCalledWith({ uri: mockDeeplink });
+  });
+
   it('subscribes to Branch deeplink events', async () => {
     DeeplinkManager.start();
     expect(branch.subscribe).toHaveBeenCalled();
@@ -318,4 +375,68 @@ describe('DeeplinkManager.start Branch deeplink handling', () => {
     await new Promise((resolve) => setImmediate(resolve));
     expect(handleDeeplink).toHaveBeenCalledWith({ uri: mockUri });
   });
+
+  it('rewrites Branch short link to link.metamask.io when +clicked_branch_link and $deeplink_path are present', async () => {
+    DeeplinkManager.start();
+    const callback = (branch.subscribe as jest.Mock).mock.calls[0][0];
+
+    callback({
+      uri: 'https://metamask-alternate.app.link/1WkF6GmE40b?amount=1000000&from=eip155%3A1%2Ferc20%3A0xabc',
+      params: {
+        '+clicked_branch_link': true,
+        $deeplink_path: 'swap',
+      },
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(handleDeeplink).toHaveBeenCalledWith({
+      uri: 'https://link.metamask.io/swap?amount=1000000&from=eip155%3A1%2Ferc20%3A0xabc',
+    });
+  });
+
+  it('passes URI through unchanged when +clicked_branch_link is false', async () => {
+    DeeplinkManager.start();
+    const callback = (branch.subscribe as jest.Mock).mock.calls[0][0];
+    const mockUri = 'https://metamask.app.link/swap?amount=100';
+
+    callback({
+      uri: mockUri,
+      params: { '+clicked_branch_link': false },
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(handleDeeplink).toHaveBeenCalledWith({ uri: mockUri });
+  });
+
+  it('passes URI through unchanged when $deeplink_path is missing', async () => {
+    DeeplinkManager.start();
+    const callback = (branch.subscribe as jest.Mock).mock.calls[0][0];
+    const mockUri = 'https://metamask.app.link/swap?amount=100';
+
+    callback({
+      uri: mockUri,
+      params: { '+clicked_branch_link': true },
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(handleDeeplink).toHaveBeenCalledWith({ uri: mockUri });
+  });
+
+  it('strips leading slash from $deeplink_path when rewriting', async () => {
+    DeeplinkManager.start();
+    const callback = (branch.subscribe as jest.Mock).mock.calls[0][0];
+
+    callback({
+      uri: 'https://metamask-alternate.app.link/ABC123',
+      params: {
+        '+clicked_branch_link': true,
+        $deeplink_path: '/swap/token',
+      },
+    });
+
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(handleDeeplink).toHaveBeenCalledWith({
+      uri: 'https://link.metamask.io/swap/token',
+    });
+  });
 });
diff --git a/app/core/DeeplinkManager/DeeplinkManager.ts b/app/core/DeeplinkManager/DeeplinkManager.ts
@@ -7,6 +7,33 @@ import Logger from '../../util/Logger';
 import { handleDeeplink } from './handlers/legacy/handleDeeplink';
 import FCMService from '../../util/notifications/services/FCMService';
 import AppConstants from '../AppConstants';
+import { BranchParams } from './types/deepLinkAnalytics.types';
+
+/**
+ * When Branch resolves a short link (e.g. metamask-alternate.app.link/1WkF6GmE40b),
+ * the URI path may be link ID, not an in-app route. If the resolved params indicate
+ * a clicked Branch link with a $deeplink_path, replace the host and path segment
+ * with link.metamask.io/$deeplink_path while preserving the original query string.
+ */
+export function rewriteBranchUri(
+  uri: string | undefined,
+  params: BranchParams | undefined,
+): string | undefined {
+  try {
+    if (!uri || !params?.['+clicked_branch_link']) return uri;
+    const rawPath = params.$deeplink_path;
+    if (typeof rawPath !== 'string') return uri;
+
+    const parsed = new URL(uri);
+    parsed.host = AppConstants.MM_IO_UNIVERSAL_LINK_HOST;
+    // Set the pathname to the sanitized $deeplink_path
+    parsed.pathname = `/${rawPath.replace(/^\//, '')}`;
+    return parsed.toString();
+  } catch (error) {
+    Logger.error(error as Error, `Error rewriting Branch URI: ${uri}`);
+    return uri;
+  }
+}
 
 export class DeeplinkManager {
   // singleton instance
@@ -66,6 +93,17 @@ export class DeeplinkManager {
 
       try {
         const latestParams = await branch.getLatestReferringParams();
+
+        // Cold start: params may contain a resolved Branch link with $deeplink_path.
+        const rewritten = rewriteBranchUri(
+          latestParams?.['~referring_link'] as string | undefined,
+          latestParams as Record<string, unknown> | undefined,
+        );
+        if (rewritten) {
+          handleDeeplink({ uri: rewritten });
+          return;
+        }
+
         const deeplink = latestParams?.['+non_branch_link'] as string;
         if (deeplink) {
           handleDeeplink({ uri: deeplink });
@@ -117,12 +155,11 @@ export class DeeplinkManager {
         const branchError = new Error(error);
         Logger.error(branchError, 'Error subscribing to branch.');
       }
-      getBranchDeeplink(opts.uri);
-      //TODO: that async call in the subscribe doesn't look good to me
-      branch.getLatestReferringParams().then((val) => {
-        const deeplink = opts.uri || (val['+non_branch_link'] as string);
-        handleDeeplink({ uri: deeplink });
-      });
+      const rewritten = rewriteBranchUri(
+        opts.uri,
+        opts.params as Record<string, unknown> | undefined,
+      );
+      getBranchDeeplink(rewritten ?? opts.uri);
     });
   }
 }
diff --git a/app/core/DeeplinkManager/handlers/legacy/handleUniversalLink.ts b/app/core/DeeplinkManager/handlers/legacy/handleUniversalLink.ts
@@ -57,6 +57,7 @@ import Logger from '../../../../util/Logger';
 
 const {
   MM_UNIVERSAL_LINK_HOST,
+  MM_UNIVERSAL_LINK_HOST_ALTERNATE,
   MM_IO_UNIVERSAL_LINK_HOST,
   MM_IO_UNIVERSAL_LINK_TEST_HOST,
 } = AppConstants;
@@ -216,6 +217,7 @@ async function handleUniversalLink({
 
   const isSupportedDomain =
     urlObj.hostname === MM_UNIVERSAL_LINK_HOST ||
+    urlObj.hostname === MM_UNIVERSAL_LINK_HOST_ALTERNATE ||
     urlObj.hostname === MM_IO_UNIVERSAL_LINK_HOST ||
     urlObj.hostname === MM_IO_UNIVERSAL_LINK_TEST_HOST;
 
diff --git a/app/core/DeeplinkManager/util/deeplinks/index.ts b/app/core/DeeplinkManager/util/deeplinks/index.ts
@@ -2,6 +2,7 @@ import AppConstants from '../../../AppConstants';
 
 const {
   MM_UNIVERSAL_LINK_HOST,
+  MM_UNIVERSAL_LINK_HOST_ALTERNATE,
   MM_IO_UNIVERSAL_LINK_HOST,
   MM_IO_UNIVERSAL_LINK_TEST_HOST,
 } = AppConstants;
@@ -10,6 +11,7 @@ const METAMASK_HOSTS = [
   ...new Set(
     [
       MM_UNIVERSAL_LINK_HOST || 'link.metamask.io',
+      MM_UNIVERSAL_LINK_HOST_ALTERNATE || 'metamask-alternate.app.link',
       MM_IO_UNIVERSAL_LINK_HOST || 'link.metamask.io',
       MM_IO_UNIVERSAL_LINK_TEST_HOST || 'link-test.metamask.io',
       'metamask.app.link',
