Skip to content

deep-links.md

Latest commit

 

History

History
228 lines (176 loc) · 8.51 KB

deep-links.md

File metadata and controls

228 lines (176 loc) · 8.51 KB

Deep links

Overview

MetaMask deep links are smart URLs that dynamically route users to the most relevant point in their journey—based on their device, app status, and the action we want them to take. Deep links help reduce friction, personalize the journey, and drive higher conversion. For a link to be a deep link, it needs to have logic baked in.

Example

Here is an example of a deep link which links to a swaps feature MetaMask extension. https://link.metamask.io/swap?sig=AWqgclBcX7wDKXJ-ZbABoRU2pzVS7xQAA5UsIuWEzKVchvqyYos_w0At4zR33_0wJdFAypIJM4VgboiU3ghhUQ

  • Clicking on the deep link above would have the following behavior:
    • If a user is on DESKTOP:
      • And MetaMask extension is installed:
        • It will take the user to the Swap page.
      • And MetaMask extension is not installed:
        • It will take the user to the metamask.io/download website.

Additional notes

  • If a deep link is not registered in the extension, the error "Not found" page will be displayed.

Deep link user flow

---
title: Example user flow diagram for deep linking to swaps page
displayMode: compact
---
graph TD
  A[Click on a Deep Link for Swaps] -->|User on DESKTOP| B{MetaMask Extension Installed?}
  B -->|Yes| C{Is the Link Signed?}
  B -->|No| D[Take User to metamask.io/download]

  C -->|Yes| E[Show interstitial page with link information]
  C -->|No| F[Show interstitial page with warning]

  E --> |User Confirms| G[Take User to Swap Page]
  F -->|User Confirms| G
Loading

Creating and signing deep links

There are several steps that need to be taken to register a deep link in the MetaMask extension.

1. Construct a deep link and sign it.

For deep link construction we use branch.io features. The 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. For more information, please refer to the ADR.

Links are signed with a protected dedicated link signer, so additional access is required (ask internally for link signer application and access).

Example:

https://link.metamask.io/home?sig=mmVgbZk8ucIY8-syEWrtnRvZlrHGQgM7Jl26fgRVjuwX62UVvhUE5nxOCWn0kEbYhZ_P17nwCZBbqJU7rPMx2w

2. Register deep link route in extension

Add a new file to the deep links route folder with a name of the route (e.g., home.ts) and create route definition.

import { DEFAULT_ROUTE, Route } from './route';

export default new Route({
  pathname: '/home',
  getTitle: (_: URLSearchParams) => 'deepLink_theHomePage', // deepLink_theHomePage is a translation constant from messages.json
  handler: function handler(_: URLSearchParams) {
    return { path: DEFAULT_ROUTE, query: new URLSearchParams() };
  },
});

Directory location: https://github.com/MetaMask/metamask-extension/tree/main/shared/lib/deep-links/routes

Add new route by calling addRoute utility function in index.ts file of the deep links route folder.

import home from './home';

addRoute(home);

Additional notes

  • 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 represented by the translation constant (e.g., deepLink_theHomePage from messages.json).
    • handler - Callback function that should return an object with path and query properties.
      • 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.
    • Handler function must be synchronous.
    • Handler function must not change anything. Deep links are read-only, and all actions/changes must be confirmed by the user in the UI layer.
  • For a deeper understanding of the route definitions and their properties, check router implementation and its types.
  • For a link to work as a deferred deep link, it needs to be added to the branch.io LinkHub. For more information check deferred deep links section below.

Architecture

For a deeper understanding of the deep links implementation and its architecture, here is the abstracted class diagram that shows associations and responsibilities of the particular components in the system.

classDiagram
    class DeepLinkRouter {
        -getExtensionURL: Function
        -getState: Function
        +install()
        +uninstall()
        -handleBeforeRequest()
        -tryNavigateTo()
        -canSkipInterstitial()
        -formatUrlForInterstitialPage()
        -get404ErrorURL()
        -redirectTab()
    }

    class DeepLink {
        -description: string
        -extraDescription: string
        -route: Route
        -title: string
        -cta: string
        -skipDeepLinkInterstitialChecked: boolean
        -isLoading: boolean
        +render()
        -updateStateFromUrl()
        -onRemindMeStateChanged()
    }

    class Route {
        +pathname: string
        +getTitle: Function
        +handler: Function
        +constructor(options: RouteOptions)
    }

    class ParsedDeepLink {
        +route: Route
        +destination: Destination
        +signature: SignatureStatus
    }

    class Destination {
        +path: string
        +query: URLSearchParams
        OR
        +redirectTo: URL
    }

    class EventEmitter {
        +emit()
        +on()
    }

    class RouteRegistry {
        +routes: Map<string, Route>
        +addRoute(route: Route)
    }

    %% Route implementations
    class HomeRoute {
        +pathname: "/home"
        +getTitle()
        +handler()
    }

    class SwapRoute {
        +pathname: "/swap"
        +getTitle()
        +handler()
    }

    class NotificationsRoute {
        +pathname: "/notifications"
        +getTitle()
        +handler()
    }

    %% Define relationships
    EventEmitter <|-- DeepLinkRouter : extends
    DeepLinkRouter --> ParsedDeepLink : parses and creates
    DeepLinkRouter --> Route : uses routes from
    DeepLink --> ParsedDeepLink : displays and processes
    DeepLink --> Route : links to route
    ParsedDeepLink --> Route : contains
    ParsedDeepLink --> Destination : contains
    Route <|-- HomeRoute : implements
    Route <|-- SwapRoute : implements
    Route <|-- NotificationsRoute : implements
    RouteRegistry --> Route : registers and stores
Loading

Deep Link Router is instantiated in the background script (background.js).

Deferred deep links

Deferred deep links are used to navigate a user to a deep link route after the extension is installed. For deferred deep link to work, it is required to add the specific link with its path to the branch.io LinkHub.

The extension receives deferred deep link data from the MetaMask website, which collects that data via the integrated Branch.io SDK.

Deferred deep link flow:

  1. When a user lands on the MetaMask website download page, the website stores the deferred deep link inside cookie.
  2. When the user installs MetaMask extension, the extension reads and stores the cookie from the MetaMask website.
  3. Then extension navigates the user to the deferred deep link after successful onboarding.

Notes:

  • Deferred deep link is stored in the extension's local storage immediately after installation.
  • User is navigated to the deferred deep link only if they completed the onboarding process within the two hours after installation.

Security

It is recommended that deep links provided by MetaMask are signed. Signed links will skip the interstitial warning page and show the link information interstitial instead. Link information interstitial can be skipped next time if a user checks the "Don't remind me again" option. By signing links, it is ensured that there is a distinction between what MetaMask provides and what is coming from a community outside.