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.

In the case of Universal Linking, the user may be redirected to the browser, which may not be the desired behavior. Deep Linking ensures that the user is redirected to the app, providing a seamless experience.

The connection and sign request flows are similar across platforms. The next section provides a high-level overview of both flows.

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.

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.

Platform preparations

iOS

In order for Dapps to be able to trigger your wallet for a connection or sign request using deep links you first need to add your custom scheme under CFBundleURLTypes key in your Info.plist file.

<key>CFBundleURLTypes</key>
<array>
	<dict>
		<key>CFBundleTypeRole</key>
		<string>Editor</string>
		<key>CFBundleURLName</key>
		<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
		<key>CFBundleURLSchemes</key>
		<array>
			<string>examplewallet</string> <!-- your custom scheme goes here -->
		</array>
	</dict>
</array>

Android

In order for Dapps to be able to trigger your wallet for a connection or sign request using deep links you first need to declare an <intent-filter> in your wallet's Manifest.xml as follows:

<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="examplewallet" /> <!-- your own custom scheme -->
</intent-filter>

Flutter

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

Additionally, you would have to set FlutterDeepLinkingEnabled key to true on iOS's Info.plist file.

<key>FlutterDeepLinkingEnabled</key>
<true/>

More information in official documentation: https://docs.flutter.dev/ui/navigation/deep-linking

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

Integration

Either you are approving a session proposal or responding to a session request, redirecting back to the Dapp is as simply as launching requester's redirect object in PairingMetadata:

For session approval:

// Where event is a SessionProposalEvent
final scheme = event.params.proposer.metadata.redirect?.native ?? '';
launchUrlString(scheme, mode: LaunchMode.externalApplication);

For session requests:

final session = web3Wallet.sessions.get(topic);
final scheme = session?.peer.metadata.redirect?.native ?? '';
launchUrlString(scheme, mode: LaunchMode.externalApplication);