Universal Links on iOS and App Links on Android
If you've ever tapped a link in a message and it opened straight into an app instead of a browser, you've used Universal Links (iOS) or App Links (Android). These let a single HTTPS URL open your native app when it's installed, and fall back to the web when it isn't. This post covers how each platform verifies the connection and how to set it up correctly.
Why Not Just Use Custom URL Schemes?
Older deep linking relied on custom schemes like myapp://profile/42. These are easy to set up but have two problems: any app can register the same scheme (so another app can hijack your links), and a scheme link does nothing useful if the app isn't installed. Universal Links and App Links solve both problems because they use ordinary https:// URLs that are cryptographically verified against your domain.
How Verification Works
Both platforms use the same idea: you publish a small JSON file on your domain, and the OS fetches it at install time to confirm you own both the domain and the app.
- iOS looks for
https://yourdomain.com/.well-known/apple-app-site-association - Android looks for
https://yourdomain.com/.well-known/assetlinks.json
Because the file lives on your domain under HTTPS, only someone who controls the domain can approve an app to handle its links, which is what prevents hijacking.
Setting Up Universal Links (iOS)
1. Host an apple-app-site-association file (no file extension, served as application/json):
{
"applinks": {
"apps": [],
"details": [
{
"appID": "TEAMID.com.yourcompany.yourapp",
"paths": ["/profile/*", "/invite/*"]
}
]
}
}
2. Add the Associated Domains capability in Xcode, with an entry like:
applinks:yourdomain.com
3. Handle the incoming URL in your app, typically in SceneDelegate or via SwiftUI's onOpenURL:
.onOpenURL { url in
handleUniversalLink(url)
}
iOS fetches and caches the association file when the app is installed, so changes to it won't take effect for existing installs until the OS re-validates, which can take a reinstall or a specific re-verification trigger.
Setting Up App Links (Android)
1. Host an assetlinks.json file:
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.yourcompany.yourapp",
"sha256_cert_fingerprints": ["AA:BB:CC:...:ZZ"]
}
}]
2. Declare an intent filter with android:autoVerify="true" in your manifest:
<intent-filter android:autoVerify="true">
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<data android:scheme="https" android:host="yourdomain.com" />
</intent-filter>
3. Read the incoming data from the launching Intent:
val uri: Uri? = intent?.data
Android verifies the domain association at install time and you can check the result with adb shell pm get-app-links com.yourcompany.yourapp.
Testing Before You Ship
- Apple provides a validator at
search.developer.apple.com/appsearch-validation-toolto check your association file. - Google's Statement List Generator and the Digital Asset Links API (
https://digitalassetlinks.googleapis.com/v1/statements:list) let you verifyassetlinks.jsonindependently of a device. - Test with the app both installed and not installed — the fallback behavior (usually your website) matters just as much as the deep link itself.
Common Pitfalls
- Serving the wrong content type. The association files must be served as JSON, not HTML or plain text, and without a redirect.
- Multiple apps or environments. If you have separate debug/release builds or multiple apps on one domain, both files support arrays so you can list several app IDs or packages.
- Caching. iOS caches the association file aggressively; Android re-verifies mainly at install time. Changes to the file don't always propagate immediately to already-installed apps.
- Mismatched paths. On iOS, a path not listed in
paths(or excluded viaexcludedPaths) will not open the app, even if the domain matches. - Wrong SHA-256 fingerprint. This is the most common Android failure — make sure the fingerprint matches the signing key of the build you're testing (debug vs. release keystores differ).
Summary
Universal Links and App Links both work the same way at a high level: a JSON file on your domain proves ownership, and the OS uses that proof to route HTTPS links straight into your app. Get the association file right, test with both the validator tools and real devices, and remember that verification is cached — so give yourself time to see changes take effect.
