Skip to main content

Mobile Linking

Note

This feature is only relevant to native platforms.

Usage​

Mobile Linking allows your wallet to automatically redirect back to the Dapp allowing for less user interactions and hence a better UX for your users.

Establishing Communication Between Mobile Wallets and Apps​

When integrating a wallet with a mobile application, it's essential to understand how they communicate. The process involves two main steps:

  1. QR Code Handshake: The mobile app (Dapp) generates a unique URI (Uniform Resource Identifier) and displays it as a QR code. This URI acts like a secret handshake. When the user scans the QR code using their wallet app, they establish a connection. It's like saying, "Hey, let's chat!"
  2. Deep Links and Universal Links: The URI from the QR code allows the wallet app to create a deep link or universal link. These links work on both Android and iOS. They enable seamless communication between the wallet and the app.
tip

Developers should prefer Deep Linking over Universal Linking.

Universal Linking may redirect the user to a browser, which might not provide the intended user experience. Deep Linking ensures the user is taken directly to the app.

Key Behavior to Address​

In some scenarios, wallets use redirect metadata provided in session proposals to open applications. This can cause unintended behavior, such as:

Redirecting to the wrong app when multiple apps share the same redirect metadata (e.g., a desktop and mobile version of the same Dapp). Opening an unrelated application if a QR code is scanned on a different device than where the wallet is installed.

Recommended Approach​

To avoid this behavior, wallets should:

  • Restrict Redirect Metadata to Deep Link Use Cases: Redirect metadata should only be used when the session proposal is initiated through a deep link. QR code scans should not trigger app redirects using session proposal metadata.

The connection and sign request flows are similar across platforms.

Connection Flow​

  • Dapp Prompts User: The Dapp asks the user to connect.
  • User Chooses Wallet: The user selects a wallet from a list of compatible wallets.
  • Redirect to Wallet: The user is redirected to their chosen wallet.
  • Wallet Approval: The wallet prompts the user to approve or reject the session (similar to granting permission).
  • Return to Dapp:
    • Manual Return: The wallet asks the user to manually return to the Dapp.
    • Automatic Return: Alternatively, the wallet automatically takes the user back to the Dapp.
  • User Reunites with Dapp: After all the interactions, the user ends up back in the Dapp.
Mobile Linking Connect FlowMobile Linking Connect Flow

Sign Request Flow​

When the Dapp needs the user to sign something (like a transaction), a similar pattern occurs:

  • Automatic Redirect: The Dapp automatically sends the user to their previously chosen wallet.
  • Approval Prompt: The wallet asks the user to approve or reject the request.
  • Return to Dapp:
    • Manual Return: The wallet asks the user to manually return to the Dapp.
    • Automatic Return: Alternatively, the wallet automatically takes the user back to the Dapp.
  • User Reconnects: Eventually, the user returns to the Dapp.
Mobile Linking Sign FlowMobile Linking Sign Flow

Platform preparations​

Since React Native leverages on native APIs, you must follow iOS and Android steps for each native platform

More information in official documentation: https://reactnative.dev/docs/linking?syntax=android#enabling-deep-links

tip

Dapps developers must do the same for their own custom schemes if they want the wallet to be able to navigate back after a session approval or a sign request response

How to test​

Before submitting your project to the Cloud Explorer you can test mobile linking in our sample Dapp:

  1. On your mobile device, visit the appropriate link:
  1. Click the "Custom Wallet" button and fill in the form with your wallet information. The website will reload and your wallet will be stored locally.
  2. Click the "Connect Wallet" button and choose your mobile wallet. It should automatically open and redirect to your wallet.

Learn more about mobile linking in the Best Practices section.

Integration​

In order to redirect to the Dapp, you'll need to use Linking from react-native and call openURL() method with the Dapp scheme that comes in the proposal metadata.

import { Linking } from 'react-native'

async function onApprove(proposal, namespaces) {
  const session = await walletKit.approveSession({ id: proposal.id, namespaces })

  const dappScheme = session.peer.metadata.redirect?.native

  if (dappScheme) {
    Linking.openURL(dappScheme)
  } else {
    // Inform the user to manually return to the DApp
  }
}