Migrating from Custom URI Schemes to Universal and App Links

Modern mobile development has shifted away from seeing applications as isolated silos. Today, users expect a unified experience where a link in a browser, social media post, or email transitions them directly to a specific feature inside a native app. This mechanism is known as deep linking, and it serves as the essential bridge between web content and mobile screens.

In the early days of mobile ecosystems, developers relied on custom URI schemes to handle these transitions. While effective for simple navigation, these legacy systems lacked the security and reliability required for enterprise applications. As the industry moved toward a web-first discovery model, the architecture for linking had to evolve to solve the problem of trust and identity.

Deep linking is not just a routing mechanism; it is a fundamental shift in how we perceive the boundaries between the mobile web and native application environments.

The fundamental challenge is ensuring that the operating system knows which application should handle a specific link. Without a verification layer, any application can claim a specific protocol, leading to security vulnerabilities and a fragmented user experience. Modern protocols like Universal Links for iOS and App Links for Android address these issues by creating a cryptographically verified connection between a domain and an app.

The architecture of modern deep linking depends on a secure association between a web domain and a mobile application bundle. On iOS, this is implemented via Universal Links, while Android uses the App Links protocol. Both systems require the developer to host a JSON configuration file on their web server in a specific hidden directory.

The operating system downloads these files when the app is first installed or updated. By parsing these files, the OS builds a local database of URL patterns that are authorized to bypass the browser. This prevents malicious apps from intercepting sensitive links intended for your platform.

• Domain verification requires an active HTTPS connection with a valid certificate.
• Configuration files must be hosted in the .well-known directory of the web server.
• The MIME type for these files should be application/json to ensure proper parsing by the OS.

When a user clicks a verified link, the OS intercepts the request before it reaches the browser. It compares the URL against the patterns defined in its local database. If a match exists, the app is launched immediately with the URL passed into the application delegate or activity for further routing.

Once the OS identifies a matching link, it triggers a specific entry point within your application code. On Android, this is handled through the Intent system. The Activity responsible for deep linking must be declared in the manifest with an intent-filter that includes the autoVerify attribute set to true.

In iOS, the routing logic typically resides in the SceneDelegate or AppDelegate depending on the age of the project. Modern SwiftUI applications use the onOpenURL modifier to handle incoming links directly within the view hierarchy. Regardless of the framework, the logic involves parsing the URL to extract identifiers like product IDs or session tokens.

1override fun onCreate(savedInstanceState: Bundle?) {
2    super.onCreate(savedInstanceState)
3    
4    // Check if the activity was started by a deep link
5    val intentData = intent?.data
6    if (intentData != null) {
7        val productId = intentData.lastPathSegment
8        // Route the user to the specific product view
9        navigateToProduct(productId)
10    }
11}
12
13override fun onNewIntent(intent: Intent?) {
14    super.onNewIntent(intent)
15    // Handle links when the activity is already in the foreground
16    setIntent(intent)
17    processDeepLink(intent?.data)
18}

Handling the app lifecycle is a critical part of the implementation. If the app is already running in the background, the system might not call the standard initialization methods. Developers must implement specialized callbacks like onNewIntent on Android to ensure the deep link is processed even when the app is already warm.

Security is a primary concern when dealing with deep links because they can be used to bypass traditional authentication flows. You should never assume that the presence of a deep link implies a verified user session. Always validate session tokens or user permissions before displaying sensitive data triggered by a link.

Testing deep links requires simulating various application states. You must test what happens when the app is completely closed (cold start) versus when it is already running in the background (warm start). Use command-line tools like adb for Android or xcrun for iOS to trigger URLs without needing to send real emails or push notifications.

• Verify that the web server serves the association file without any redirects.
• Ensure the Content-Type header is strictly application/json.
• Check the size of the association file, as mobile OSs often have strict limits around 128KB.

One common pitfall is the failure of the OS to update its local link database. If you change your AASA or assetlinks file, the OS may not see the changes until the user updates the app or waits for a background refresh. During development, you may need to uninstall and reinstall the app multiple times to force a re-verification.