Migrate from custom schemes (Android)

If your application currently uses custom URL schemes such as myapp://, Trustly recommends migrating to Android App Links. App Links are more secure and provide a better user experience because they are verified against your website, and they prevent other apps from hijacking your links.

To ensure a smooth transition, you should treat the migration as an extension process. Maintain support for the custom scheme to support older app versions while adding App Links as the primary method for modern users.

Update the manifest

To support both link types simultaneously, you must keep your existing <intent-filter> for the custom scheme and add a new one for App Links. The following is the recommended methodology:

• Keep the existing filter: This ensures users on older versions of your app, or links hardcoded in emails using myapp://, continue to work.
• Add the App Link filter: This enables the modern HTTPS handling.

Open your AndroidManifest.xml file and add the following entry:

1
<activity android:name=".MainActivity">
2
3
    <intent-filter>
4
        <action android:name="android.intent.action.VIEW" />
5
        <category android:name="android.intent.category.DEFAULT" />
6
        <category android:name="android.intent.category.BROWSABLE" />
7
        <data android:scheme="myapp" />
8
    </intent-filter>
9
10
    <intent-filter android:autoVerify="true">
11
        <action android:name="android.intent.action.VIEW" />
12
        <category android:name="android.intent.category.DEFAULT" />
13
        <category android:name="android.intent.category.BROWSABLE" />
14
        
15
        <data android:scheme="https" />
16
        <data android:host="your-domain.com" />
17
        <data android:pathPrefix="/products" />
18
    </intent-filter>
19
20
</activity>

Create a unified router

To ensure a successful migration, your handling logic must process the Uri in a scheme-agnostic way. Since Android delivers the complete Uri object to your Activity regardless of the source, you can create a single function to route the user.

The following example demonstrates how to handle both https and myapp schemes using the same logic.

1
private fun handleDeepLink(appUri: Uri) {
2
    println("Incoming URI: $appUri")
3
4
    // Inspect the scheme to determine the source
5
    if (appUri.scheme == "https") {
6
        println("Detected App Link (Modern)")
7
    } else if (appUri.scheme == "myapp") {
8
        println("Detected Deep Link (Legacy)")
9
    }
10
11
    // Extract the path and query parameters using standard Uri functions.
12
    // This logic works identically for both schemes.
13
    val path = appUri.path
14
    
15
    if (path?.startsWith("/products") == true) {
16
        val productId = appUri.getQueryParameter("id")
17
        if (productId != null) {
18
            navigateToProductDetail(productId)
19
        }
20
    }
21
}

By using standard Uri functions to get the path and parameters, you simplify maintenance. When the App Link is verified, it automatically takes precedence over the custom scheme without requiring you to rewrite your internal navigation logic.