Add documentation for deep links #158

david0xd · 2025-11-13T15:10:21Z

This PR adds contributor documentation for deep links.

Click here for rendered markdown version.

Note

Adds comprehensive Deep Links guidelines in docs/deep-links.md and links it from README.md.

Documentation:
- New guide: Adds docs/deep-links.md detailing deep links overview, example behavior, user flow (mermaid), creation/signing with Branch, route registration in the extension (with code samples), architecture (class diagram), and security recommendations.
- README: Adds link to docs/deep-links.md in the table of contents.

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

davidmurdoch

Just a quick pass. I'll need to read more in depth later.

davidmurdoch · 2025-11-17T15:35:58Z

docs/deep-links.md

+
+```mermaid
+---
+title: Examole user flow diagram for deep linking to swaps page


Suggested change

title: Examole user flow diagram for deep linking to swaps page

title: Example user flow diagram for deep linking to swaps page

davidmurdoch · 2025-11-17T15:36:24Z

docs/deep-links.md

+title: Examole user flow diagram for deep linking to swaps page
+displayMode: compact
+---
+graph TD


graph text is cut off in many areas.

I tried to fix few things. Let me know if it helps or what exactly you think should be better.

davidmurdoch · 2025-11-17T15:36:47Z

docs/deep-links.md

+  B -->|Yes| C{Is the Link Signed?}
+  B -->|No| D[Take User to metamask.io/download]
+
+  C -->|Yes| E[Skip Interstitial Warning Page\n and show link info page once]


there is an interstitial screen for signed links as well.

I updated this description now.

davidmurdoch · 2025-11-17T15:38:39Z

docs/deep-links.md

+Branch service is configured and automatically capable of linking any path to the extension route, if the route is registered.
+So, adding `/home` or `/swap` at the end of `link.metamask.io` would be enough, and there is no need for additional configurations on the Branch side.
+
+Internal deep links are supposed to be signed and skip interstitial (warning page).


There is no such think as "internal" deep links. And there is an interstitial shown for both signed and unsigned links.

Updated the terminology and description around this. Let me know if it helps.

davidmurdoch · 2025-11-17T15:40:44Z

docs/deep-links.md

+Branch service is configured and automatically capable of linking any path to the extension route, if the route is registered.
+So, adding `/home` or `/swap` at the end of `link.metamask.io` would be enough, and there is no need for additional configurations on the Branch side.


You should clarify this. The wording here on the first sentence makes it seems like the link MUST be registered in branch. I know what you mean, but it can be easily be read to mean the opposite of what you intended.

I tried to explain this in a better way. Let me know if it's good enough or any other advice if you have.

davidmurdoch · 2025-11-17T15:41:24Z

docs/deep-links.md

+
+export default new Route({
+  pathname: '/home',
+  getTitle: (_: URLSearchParams) => 'deepLink_theHomePage',


mention that this is a translation key (in messages.json)

Added comment.

davidmurdoch · 2025-11-17T15:42:00Z

docs/deep-links.md

+
+- Deep link route definition consists of:
+  - `pathname` - Route path identifier (e.g., `/home`, `/swaps`, `/notifications`)
+  - `getTitle` - Callback function that should return title of the deep link page. This is usually represented by the translation constant (e.g., `deepLink_theHomePage`).


Not usually though. Always.

davidmurdoch · 2025-11-17T15:44:12Z

docs/deep-links.md

+    - `path` - Exact path of the route used in extension. Taken from the existing routes definitions (e.g., `DEFAULT_ROUTE`, `NOTIFICATIONS_ROUTE`).
+    - `query` - URL query params. Constructed using `URLSearchParams` constructor function.
+- Make sure that the route exists and return it from a handler under `path` key.
+- Handler function can transform query parameters if necessary.


its worth noting that

a) it must be synchronous.
b) it must NEVER change anything. Deep links are read only and all actions/changes must be confirmed by the user in the UI layer.

Updated. I added what you suggested.

davidmurdoch · 2025-11-17T15:44:33Z

docs/deep-links.md

+    RouteRegistry --> Route : registers and stores
+```
+
+Deep Link Router is instantiated in service worker ([background.js](https://github.com/MetaMask/metamask-extension/blob/main/app/scripts/background.js#L757)).


Not if its in Firefox where there are now service workers.

I wrote this in a little bit different way now. Let me know if calling it just background script is better or we should clarify something more?

davidmurdoch · 2025-11-17T15:45:18Z

docs/deep-links.md

+
+## Security
+
+Internal deep links are supposed to be signed and signed links will skip interstitial (warning page).


Don't use "internal". All links are public.

Updated this now to explain it better.

aorlovskiy · 2025-11-21T12:26:15Z

docs/deep-links.md

+Branch service is configured and automatically capable of linking to any path registered within the extension as a deep link route.
+So, adding `/home` or `/swap` at the end of `link.metamask.io` would be enough, and there is no need for additional configurations on the Branch side.
+
+Signed deep links will skip the interstitial warning page and show the link information interstitial instead.


Makes sense to link the original ADR here with more explanation of trusted/untrusted flow:
https://github.com/MetaMask/decisions/blob/dcb42a5395507928e87c183dd1809c83d9cb408d/decisions/core/0007-deep-linking-into-wallet.md

Added, as you suggested.

Add documentation for deep links

43d289e

david0xd self-assigned this Nov 13, 2025

david0xd requested a review from a team as a code owner November 13, 2025 15:10

Fix lint

6a11203

davidmurdoch requested changes Nov 17, 2025

View reviewed changes

david0xd added 2 commits November 17, 2025 17:38

Add some documentation changes

14a0700

Fix lint

f61bf04

aorlovskiy reviewed Nov 21, 2025

View reviewed changes

david0xd added 2 commits November 21, 2025 15:22

Add a link to the ADR, as suggested

8fa1907

Fix lint

9569b69

	title: Examole user flow diagram for deep linking to swaps page
	title: Example user flow diagram for deep linking to swaps page

		Branch service is configured and automatically capable of linking any path to the extension route, if the route is registered.
		So, adding `/home` or `/swap` at the end of `link.metamask.io` would be enough, and there is no need for additional configurations on the Branch side.


		## Security

		Internal deep links are supposed to be signed and signed links will skip interstitial (warning page).

Uh oh!

Add documentation for deep links #158

Are you sure you want to change the base?

Add documentation for deep links #158

Uh oh!

Conversation

david0xd commented Nov 13, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidmurdoch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

david0xd commented Nov 13, 2025 •

edited by cursor bot

Loading