When someone taps a link to your website on their mobile device, they could land in a mobile browser or seamlessly open your native app. The difference comes down to deep linking configuration that connects your domain to your mobile applications.
Apple Universal Links and Android App Links create this bridge between web URLs and app experiences. When properly configured, these technologies detect installed apps and route users accordingly, while falling back to browser experiences for users without the app installed.
Setting up this functionality requires coordination between your domain, your web server, and your mobile app code. The process involves specific configuration files, strict security requirements, and attention to caching behavior that can make troubleshooting tricky. Why Deep Links Matter
Deep linking transforms how users interact with your mobile presence. Instead of generic app launches that open to a home screen, deep links take users directly to relevant content within your app.
Consider a user who receives an email containing a link to a product page on your site. Without deep linking, tapping that link opens a mobile browser, loads your website, and requires the user to navigate manually if they want to switch to your app. With deep linking configured, the same tap opens your app directly to that specific product page.
This seamless transition improves user experience and increases engagement. Users spend less time navigating and more time interacting with content. Conversion rates typically improve when friction decreases.
Deep links also enable sophisticated marketing campaigns. You can create trackable URLs that measure how users flow from emails, social posts, or ads into specific app experiences. Attribution becomes clearer when you can follow the complete user journey.
How Universal Links and App Links Work
Both Apple and Android use similar approaches with platform-specific implementation details.
The core concept involves placing a verification file on your web server at a specific location. This file lists which apps are authorized to handle links from your domain. Mobile operating systems download this file and use it to determine whether taps on your links should open apps or browsers.
For Apple devices, this file is named apple-app-site-association and lives at https://yourdomain.com/.well-known/apple-app-site-association. For Android, the file is assetlinks.json at https://yourdomain.com/.well-known/assetlinks.json.
When a user installs your app, their device downloads these verification files from your domain. The device then knows that future taps on your domain's links should attempt to open your app first.
Security is built into this process. The verification files must be served over HTTPS, confirming that you control both the domain and the app. This prevents malicious apps from hijacking links to domains they don't own.
HTTPS Requirements
Deep linking requires valid HTTPS configuration on your domain. This isn't optional or negotiable—devices will not download verification files over insecure HTTP connections.
Your SSL certificate must be current and properly configured. Self-signed certificates won't work because mobile devices validate certificate chains against trusted certificate authorities. The HTTPS requirement extends to the entire verification file request. If your server redirects from HTTP to HTTPS, that's acceptable, but the final response must be secure. Mixed content or certificate warnings will cause verification to fail.
Beyond the verification files, any URLs you use in deep links should also be HTTPS. While technically possible to deep link to HTTP URLs, doing so creates security warnings for users and may not work reliably across all devices and OS versions.
Setting Up Apple Universal Links
Apple Universal Links require both server-side and app-side configuration.
Creating the apple-app-site-association File
This JSON file declares which apps can handle links from your domain. A minimal example looks like:
"appID": "TEAMID.com.yourcompany.yourapp",
The appID combines your Apple Team ID with your app's bundle identifier. You can find your Team ID in your Apple Developer account. The bundle identifier matches what you specified when creating your app.
The paths array specifies which URL patterns this app should handle. Using ["*"] means the app handles all paths on your domain. You can restrict this to specific paths like ["/products/*", "/blog/*"] if you want only certain sections to open in the app.
Hosting the File Correctly
Upload this file to your web server at /.well-known/apple-app-site-association. Note there's no file extension—the filename is exactly as shown.
The file must be served with the application/json content type. Some web servers require explicit configuration to serve extensionless files with the correct MIME type.
The file must be accessible without authentication or cookies. Apple's servers fetch this file when users install your app, and they won't handle login flows or session management.
Configuring Your iOS App
In your Xcode project, enable the Associated Domains capability. Add an entry formatted as applinks:yourdomain.com. Don't include https:// or any path information—just the domain.
In your app code, implement the application(_:continue:restorationHandler:) method in your App Delegate. This method receives the URL when a Universal Link opens your app:
func application(_ application: UIApplication,
continue userActivity: NSUserActivity,
restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
let url = userActivity.webpageURL else {
// Handle the URL and navigate to the appropriate screen
Your handleDeepLink function parses the URL and determines which screen to display. This might involve extracting product IDs from the path, parsing query parameters, or looking up content based on URL slugs.
Setting Up Android App Links
Android App Links follow a parallel process with different file formats.
Creating the assetlinks.json File
Android's verification file also uses JSON with a different structure:
"relation": ["delegate_permission/common.handle_all_urls"],
"namespace": "android_app",
"package_name": "com.yourcompany.yourapp",
"sha256_cert_fingerprints": [
"14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
The package_name matches your app's package name in Android Studio. The sha256_cert_fingerprints array contains SHA-256 hashes of your app signing certificates.
You need fingerprints for all certificates you use to sign your app. This typically includes your release certificate and may include debug certificates if you want deep linking to work during development.
Generate the SHA-256 fingerprint using the keytool command:
keytool -list -v -keystore your-keystore.jks -alias your-key-alias
Copy the SHA-256 fingerprint from the output and format it with colons separating each byte, as shown in the example above.
Hosting the File
Upload this file to /.well-known/assetlinks.json on your web server. Like the Apple file, it must be served over HTTPS with the application/json content type and must be publicly accessible.
Configuring Your Android App
In your Android app's manifest file, add an intent filter to the activity that should handle deep links:
<activity android:name=".MainActivity">
<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" />
<data android:host="yourdomain.com" />
The android:autoVerify="true" attribute triggers automatic verification when users install your app. Android downloads the assetlinks.json file and verifies the fingerprints match.
In your activity code, handle the incoming intent:
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
override fun onNewIntent(intent: Intent) {
super.onNewIntent(intent)
private fun handleIntent(intent: Intent) {
val data: Uri? = intent.data
// Parse the URL and navigate appropriately
Caching Challenges and Solutions
Both iOS and Android cache verification files aggressively, which creates challenges during development and updates.
iOS Caching Behavior
iOS downloads the apple-app-site-association file when users install your app. Once downloaded, iOS caches this file and doesn't check for updates frequently.
If you update your verification file, existing users won't see the changes immediately. iOS may take hours or days to refresh its cache, depending on various factors outside your control.
During development, this caching causes frustration. You make changes to your verification file, but your test device continues using the old cached version.
One workaround involves changing your domain during testing. If your production domain is yourdomain.com, use a subdomain like app-testing.yourdomain.com for development. When you need to test a new configuration, switch to a different subdomain that iOS hasn't cached yet.
Another approach uses the uninstall-reinstall cycle. Uninstalling your app clears cached verification data. After reinstalling, iOS fetches the verification file fresh. This works but becomes tedious with frequent changes.
Android Caching Behavior
Android also caches assetlinks.json files but provides slightly better tools for clearing this cache.
During development, you can clear app data for your application, which forces Android to re-verify deep link associations. This is faster than uninstalling and reinstalling.
Android Studio's App Links Assistant provides verification testing tools. You can use these to check whether Android successfully verified your domain without needing to test the full user flow.
Production caching issues on Android follow similar patterns to iOS. Updates to your assetlinks.json file won't immediately affect existing users who have your app installed.
Cache-Friendly Configuration Strategies
Design your verification files to minimize the need for future updates.
Use wildcard paths whenever possible. Instead of listing individual paths like ["/product/123", "/product/456"], use ["/product/*"]. This handles all product pages without requiring verification file updates when you add new products.
Include all future certificate fingerprints upfront if you know them. If you're planning to rotate signing certificates soon, add the new certificate's fingerprint to assetlinks.json before the rotation. Both certificates work simultaneously, preventing a verification gap during the transition.
Maintain separate subdomains for different app versions if needed. If you're running a major app redesign that requires different deep link handling, consider using v2.yourdomain.com with its own verification files. This allows gradual migration without affecting existing users.
Testing Deep Links
Proper testing requires checking multiple scenarios across different environments.
Testing on Physical Devices
Emulators and simulators don't always replicate deep linking behavior accurately. Test on physical devices running different OS versions to catch compatibility issues.
For iOS, send yourself a link via iMessage, Notes, or Mail. Tap the link and verify your app opens correctly. Long-press the link to check whether iOS offers to open it in your app—this menu option only appears when Universal Links are properly configured.
For Android, share a link to yourself via Gmail, Messages, or any app that displays clickable URLs. Tap the link and verify it opens your app. Android may show a disambiguation dialog if multiple apps can handle the URL; your app should appear in this list.
Testing the Fallback Experience
Verify that users without your app installed see appropriate fallback behavior. Links should open in the mobile browser and display your website correctly.
Test this by uninstalling your app and tapping links. The browser experience should be functional and shouldn't show error messages about missing apps.
Testing Edge Cases
Check how your app handles malformed URLs or unexpected parameters. What happens if someone manually constructs a URL to a resource that doesn't exist? Your app should handle errors gracefully and show appropriate messages.
Test URLs with special characters, very long query strings, or unusual encodings. Robust URL parsing prevents crashes or security issues.
Validation Tools
Several tools help verify your configuration without relying solely on device testing.
Apple's Validator
Apple provides an App Site Association file validator at developer.apple.com. Enter your domain and app ID to check whether Apple's servers can successfully fetch and parse your verification file.
This tool reveals HTTP errors, JSON parsing issues, and certificate problems. It's invaluable for troubleshooting why Universal Links aren't working.
Android's Statement List Generator
Google offers a Statement List Generator and Tester in Search Console. These tools verify your assetlinks.json file is correctly formatted and accessible.
The tester shows exactly what Android sees when it attempts to verify your domain, including any errors or warnings.
Command-Line Verification
You can manually check your verification files using curl:
curl -v https://yourdomain.com/.well-known/apple-app-site-association
curl -v https://yourdomain.com/.well-known/assetlinks.json
Look for successful 200 responses, correct content types, and valid JSON in the response body. Any redirects, authentication requirements, or certificate warnings indicate problems.
Handling Multiple Domains and Subdomains
Apps often need to handle links from multiple domains or subdomains.
Subdomain Configuration
If your app should handle links from both www.yourdomain.com and app.yourdomain.com, place verification files on both domains.
For iOS, add multiple Associated Domain entries in your app: applinks:www.yourdomain.com and applinks:app.yourdomain.com. Each domain needs its own apple-app-site-association file.
For Android, add multiple intent filters or multiple <data android:host="..." /> tags within a single intent filter. Each referenced domain needs its own assetlinks.json file.
Wildcard Subdomains
Apple supports wildcard subdomain patterns using the format applinks:*.yourdomain.com. This covers all subdomains with a single Associated Domain entry.
However, you still need to place the apple-app-site-association file on each subdomain. The wildcard simplifies app configuration but doesn't eliminate the need for verification files on each subdomain.
Android doesn't support wildcard subdomains in the same way. You must explicitly list each subdomain in your intent filters.
Migration During Rebrands
Rebranding that involves changing your domain requires careful deep link migration.
Maintaining Old Domain Verification
Keep verification files active on your old domain for an extended period after rebranding. Many users won't update apps immediately, and their devices still reference the old domain.
If you abandon your old domain entirely, users with older app versions may experience broken deep linking. Links that previously opened your app will fall back to browser views.
Supporting Both Domains Simultaneously
Configure your app to handle links from both your old and new domains during the transition period. Add Associated Domains entries for both domains on iOS, and multiple host declarations on Android.
Your app's URL handling code should recognize both domains and route users appropriately. This might mean normalizing URLs internally to a canonical format regardless of which domain was used.
Redirecting Web Traffic
On your old domain, implement HTTP redirects to your new domain. When users without your app tap old links, they should land on the correct page on your new domain.
These redirects don't help users who have your app installed, since deep linking bypasses the redirect. The app handles the link before any HTTP request occurs. That's why maintaining verification files on both domains is necessary.
Communicating the Change
Notify users about the domain change through in-app messages, emails, or push notifications. Encourage them to update to the latest app version that supports your new domain.
Provide a transition timeline. Users deserve to know when you'll stop supporting deep links on the old domain, giving them time to update.
Troubleshooting Common Problems
When deep links don't work as expected, systematic troubleshooting identifies the issue.
Links Open in Browser Instead of App
This usually indicates verification failed. Check that your verification file is accessible via HTTPS, returns a 200 status code, and contains valid JSON with correct app identifiers.
Verify the file's content type is application/json. Some servers serve unknown file types as text/plain, which causes validation failures.
On iOS, check that your app includes the correct Associated Domains entitlement and that the domain matches exactly. Even small differences like www vs no www cause mismatches.
On Android, verify your certificate fingerprint matches what's in assetlinks.json. Signing your app with a different certificate than specified in the file causes verification to fail.
Links Work Inconsistently
Caching often causes inconsistent behavior. One test device might use cached verification data while another fetches fresh data.
Try testing with a completely different domain or subdomain that hasn't been cached. If deep links work on the new domain, caching is likely the issue.
Wait 24-48 hours after making changes to verification files. Caching can persist for this long, and impatient troubleshooting leads to false conclusions.
App Opens But Shows Wrong Content
This indicates your verification works correctly, but your app's URL routing logic has issues. Review your URL parsing code and ensure it correctly handles all the URL patterns you've configured.
Add logging to your URL handling code. Print the incoming URL, extracted parameters, and routing decisions. This visibility helps identify where the logic breaks down.
Deep Links Stopped Working After App Update
If deep links broke after an app update, check whether you changed your bundle identifier (iOS) or package name (Android). These identifiers must remain consistent with your verification files.
Certificate changes on Android also break deep linking if you don't update assetlinks.json with the new certificate's fingerprint.
Security Considerations
Deep linking creates potential security concerns that proper implementation addresses.
Validate All Input
Never trust data in URLs. Users or malicious actors might craft URLs with unexpected values that could exploit vulnerabilities in your app.
Validate and sanitize all parameters extracted from URLs. Check that IDs are valid formats, strings don't contain injection attacks, and values fall within expected ranges.
Handle Sensitive Operations Carefully
If a deep link triggers sensitive operations like payments or account changes, require additional authentication. Don't allow a URL alone to authorize important actions.
Consider deep links as suggestions for navigation rather than commands to execute operations. Show users the relevant screen and let them explicitly confirm actions.
Prevent Clickjacking
When users tap links, they should understand where those links lead. Malicious actors could disguise links to your domain to trick users into opening your app in unexpected states.
Display clear indicators within your app about what content users are viewing and why. If a deep link led them to a payment screen, make that obvious rather than dropping them in without context.
Analytics and Attribution
Deep links enable sophisticated tracking of user journeys from external sources into your app.
Tracking Link Sources
Add query parameters to your links to track their source. A URL like https://yourdomain.com/product/123?source=email&campaign=spring provides context about where the user came from.
Your app's URL handling code can extract these parameters and send them to your analytics platform. This creates attribution data connecting external marketing to in-app behavior.
Measuring Deep Link Performance
Track how often deep links successfully open your app versus falling back to browser views. The ratio helps measure your app's market penetration.
Monitor which paths are accessed via deep links most frequently. This reveals which content resonates with users and which marketing campaigns drive the most engaged traffic.
A/B Testing Deep Link Experiences
Use deep link parameters to test different onboarding flows or promotional content. Links with ?variant=a could show one experience while ?variant=b shows another.
Measure conversion rates and engagement for each variant. Deep linking combined with A/B testing provides powerful optimization opportunities.
Advanced Patterns
Beyond basic deep linking, several advanced patterns solve specific challenges.
Deferred Deep Linking
When a user without your app installed taps a link, they go to the app store to download your app. After installation, deferred deep linking remembers the original URL and takes them to that content on first launch.
This requires coordination between your website, app store listing, and app. Third-party SDKs often handle this complexity, but implementing it yourself requires storing the URL intent somewhere accessible across the installation flow.
Contextual Deep Links
Pass rich context about the user's current state through deep links. Instead of just linking to a product page, include information about where the user came from, what they were looking at, or what action they were attempting.
This context enables more sophisticated app experiences that maintain user flow even when transitioning from web to app.
Cross-App Deep Linking
If you maintain multiple apps, you can use deep links to navigate between them. One app can open specific content in another app you publish, creating integrated experiences across your app portfolio.
This requires careful coordination of URL schemes and verification files across all your apps.
Platform-Specific Quirks
Each platform has unique behaviors worth understanding.
iOS Peculiarities
iOS sometimes presents users with a banner asking whether links should open in the app or browser. Users can choose a preference, overriding your deep link configuration.
The banner appears inconsistently based on user behavior patterns that Apple doesn't fully document. If users repeatedly choose the browser option, iOS may stop offering to open links in your app.
Android Peculiarities
Android allows multiple apps to claim the same domain. If users have multiple apps installed that all declare intent filters for your domain, Android shows a disambiguation dialog.
This can create confusion if competing apps maliciously claim your domain. The verification process through assetlinks.json should prevent unauthorized apps from successfully verifying, but the intent filter still allows them to present themselves as options.
Future-Proofing Your Configuration
As platforms evolve, deep linking technologies change. Design your implementation to accommodate future updates.
Monitor Platform Updates
Apple and Google regularly update their deep linking requirements. Subscribe to developer newsletters and review platform documentation periodically to catch changes.
Major OS updates sometimes introduce breaking changes or new requirements. Test your deep links on beta OS versions before public release to catch issues early.
Document Your Implementation
Maintain clear documentation of your deep link configuration. Future developers working on your app need to understand how URLs map to app screens and what verification files exist.
Include this documentation in your repository alongside code. It should cover URL patterns you support, parameter conventions you use, and any special handling for specific paths.
Build Flexible URL Routing
Design your URL handling code to accommodate new URL patterns without requiring complete rewrites. Use pattern matching or routing libraries rather than hardcoded if-else chains.
As your app grows and adds features, you'll need to support new URL patterns. Flexible routing architecture makes this easier.
The Payoff
Setting up Universal Links and App Links requires careful coordination between multiple systems, but the improved user experience justifies the effort.
Users who tap links to your content spend less time navigating and more time engaging. Marketing campaigns gain new attribution capabilities. Your app integrates more seamlessly into users' digital lives.
The technical requirements, HTTPS configuration, verification files, app code changes, are all achievable with systematic implementation. Following the patterns outlined here, testing thoroughly, and monitoring for issues creates reliable deep linking that works consistently across platforms.
.png&w=2048&q=75)
