Table of Contents
By Khimananda Oli | Last reviewed: August 2026
Users abandon apps when external links fail to open the correct screen or redirect to a generic homepage instead of specific content. Implementing deep linking in mobile apps solves this friction by mapping URIs directly to native views, ensuring marketing campaigns, password resets, and shared content land users exactly where they expect. This guide covers the architectural patterns, platform-specific configurations, and security validations required to build a production-grade linking system that works reliably across iOS and Android.
How do you configure deep linking in mobile apps for iOS and Android?
Configuration differs fundamentally between platforms because Apple and Google enforce distinct security models for claiming URI ownership. While legacy custom schemes (e.g., myapp://) still exist, modern implementations must prioritize verified HTTPS links to avoid ambiguity and ensure reliable behavior. For teams managing backend infrastructure alongside mobile development, understanding these server-side dependencies is as critical as the client code; misconfigured verification files are the most common cause of failure I see in audits. If you are also managing database backends for user data, reviewing PostgreSQL administration essentials ensures your user-profile endpoints return the metadata needed for dynamic link resolution.
iOS Universal Links Configuration
iOS requires two matching components: an entitlement in the app and a hosted JSON file on the server. The system checks the apple-app-site-association (AASA) file at the domain root before allowing the app to handle the link. This file must be served over HTTPS with Content-Type: application/json and cannot redirect.
<!-- ios/Runner/Runner.entitlements -->
<key>com.apple.developer.associated-domains</key>
<array>
<string>applinks:example.com</string>
<string>applinks:*.example.com</string>
</array>The corresponding AASA file defines which paths map to which Team ID and Bundle ID combinations. Wildcards are supported but should be scoped tightly to prevent hijacking unrelated subpaths.
// https://example.com/.well-known/apple-app-site-association
{
"applinks": {
"apps": [],
"details": [
{
"appID": "TEAMID.com.example.app",
"paths": ["/products/*", "/profile/*", "/reset-password"]
}
]
}
}Android App Links Configuration
Android uses Digital Asset Links (DAL) via an assetlinks.json file and manifest intent filters. Unlike iOS, Android allows multiple apps to claim the same domain if all verify successfully, but only the first verified app handles links by default unless explicitly configured otherwise. The intent filter must include android:autoVerify="true" to trigger automatic verification at install time.
<!-- android/app/src/main/AndroidManifest.xml -->
<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="example.com" android:pathPrefix="/products/" />
</intent-filter>The asset links file binds the package name to the SHA-256 fingerprint of your signing key. You can retrieve this fingerprint using keytool -list -v -keystore release.keystore. Never use debug keys for production verification.
// https://example.com/.well-known/assetlinks.json
[{
"relation": ["delegate_permission/common.handle_all_urls"],
"target": {
"namespace": "android_app",
"package_name": "com.example.app",
"sha256_cert_fingerprints": ["AA:BB:CC:..."]
}
}]What is the difference between URL schemes and Universal Links?
Understanding this distinction prevents costly rework. Custom URL schemes are proprietary protocols registered locally on the device, while Universal Links (iOS) and App Links (Android) are standard HTTPS URLs verified against a remote authority. The choice impacts security, user experience, and long-term maintainability.
| Feature | Custom URL Scheme | Universal / App Links |
|---|---|---|
| Protocol | Custom (e.g., myapp://) | Standard HTTPS |
| Ownership Verification | None (first-come-first-served) | Server-side JSON validation |
| Collision Risk | High (any app can register) | None (domain-bound) |
| Fallback Behavior | OS error or blank page | Opens in browser seamlessly |
| User Trust | Often triggers security warnings | Transparent, native feel |
| Deferred Linking | Not natively supported | Supported via SDKs or custom logic |
In practice, retain custom schemes only as a fallback for older OS versions or internal testing. All public-facing links in emails, SMS, and ads should use verified HTTPS links. This aligns with how observability systems track traffic; treating app links as standard web requests simplifies correlation between marketing attribution and in-app events, a pattern discussed in metrics, logs, and traces compared.
How does deferred deep linking work when the app is not installed?
Deferred deep linking preserves the intended destination through the app store installation process. When a user clicks a link without the app installed, the system redirects to the store, and after installation, the app retrieves the original link parameters to navigate correctly. Neither iOS nor Android provides a native, reliable API for this; it requires either a third-party SDK or a custom clipboard/server-side token approach.
- Capture Context Pre-Install: When the user lands on the web fallback page, store the intended path and parameters in a server-side session keyed by device fingerprint (IP + User-Agent hash) or write a token to the clipboard (with user permission).
- Store Installation: User installs the app from the store. No link data passes through the store itself.
- Post-Install Retrieval: On first launch, the app queries your attribution endpoint with the same fingerprint or reads the clipboard token. The server returns the original deep link payload.
- Navigation & Cleanup: The app parses the payload, navigates to the target screen, and immediately invalidates the token to prevent replay on subsequent launches.
A common mistake is relying solely on IP address for fingerprinting. In Nepal and many regions with carrier-grade NAT, thousands of users share the same public IP, causing false matches. Augment with User-Agent, screen resolution, timezone, and locale to improve accuracy. For fintech apps handling sensitive transactions, review data protection basics for Nepal fintech to ensure deferred link tokens don’t leak PII or become attack vectors.
How do you troubleshoot broken deep links in production?
Broken links usually stem from verification failures, not routing logic. Start by validating the server-side configuration before touching app code. Both platforms provide diagnostic tools that eliminate guesswork.
- iOS AASA Validator: Use Apple’s official validator or
curl -I https://example.com/.well-known/apple-app-site-associationto confirm 200 status, correct content type, and no redirects. Cache invalidation can take up to 24 hours after changes; use the?mode=developermode in TestFlight to bypass caching during testing. - Android Asset Links Tool: Run
adb shell pm verify-app-links --re-verify com.example.appto force re-verification. Check status withadb shell pm get-app-links com.example.app. Ensure the assetlinks.json is accessible without authentication and returns valid JSON. - Path Matching Debugging: Both platforms match paths case-sensitively. Verify trailing slash consistency;
/products/does not match/productson Android. Use explicit path patterns over broad wildcards during development to isolate issues. - Test on Real Devices: Simulators often skip verification or use cached states. Always validate on physical devices with clean installs after server config changes.
Implementing Secure and Maintainable Deep Linking in Mobile Apps
Treat deep links as public API endpoints. Validate every parameter server-side before generating links, sanitize inputs in the app before navigation, and never trust link payloads for authentication or financial operations without additional verification. Implement rate limiting on your attribution endpoints to prevent abuse, and log all link resolutions with correlation IDs to support incident response. Monitor verification status as part of your SLOs; a dropped AASA file is a user-facing outage even if your servers are healthy. For teams building comprehensive observability around these flows, integrating OpenTelemetry as described in instrumenting apps with OpenTelemetry provides end-to-end visibility from email click to in-app conversion.
If your current linking implementation relies on unverified schemes or lacks fallback handling, audit your configuration this week. Start by validating your AASA and assetlinks.json files, then instrument link resolution events to measure real-world success rates. For architecture reviews or compliance-focused deep link implementations, reach out to discuss your specific requirements.
