Capacitor apps are web apps wrapped in a native shell. Deep linking in Capacitor requires native configuration (AASA, assetlinks.json, entitlements, Intent filters) plus JavaScript-side URL handling. This guide covers both sides.<\/p>\n\n\n\n
For the cross-platform deep linking overview, see cross-platform deep linking guide for 2026<\/a>. For Ionic-specific configuration, see Ionic deep linking: complete configuration guide<\/a>.<\/p>\n\n\n\n In Xcode, open your project (the This creates or updates the Host at Capacitor's default This forwards Universal Link URLs to Capacitor's bridge, which makes them available to your JavaScript code.<\/p>\n\n\n\n Edit Host at Get your fingerprint:<\/p>\n\n\n\n Capacitor's built-in Deep links can arrive when the app is:<\/p>\n\n\n\n Handle the cold start case by checking for a URL on app initialization:<\/p>\n\n\n\n During development, you can test routing logic in the browser by navigating directly to the path:<\/p>\n\n\n\n This tests the routing logic but not the native deep link handling.<\/p>\n\n\n\nPrerequisites<\/h2>\n\n\n\n
\n
\/.well-known\/apple-app-site-association<\/code><\/li>\n\/.well-known\/assetlinks.json<\/code><\/li>\n<\/ul>\n\n\n\niOS Configuration<\/h2>\n\n\n\n
1. Add Associated Domains Entitlement<\/h3>\n\n\n\n
ios\/App<\/code> directory):<\/p>\n\n\n\n\n
applinks:yourdomain.com<\/code><\/li>\n<\/ol>\n\n\n\n.entitlements<\/code> file:<\/p>\n\n\n\n<key>com.apple.developer.associated-domains<\/key>\n<array>\n <string>applinks:yourdomain.com<\/string>\n<\/array>\n<\/code><\/pre>\n\n\n\n2. AASA File<\/h3>\n\n\n\n
https:\/\/yourdomain.com\/.well-known\/apple-app-site-association<\/code>:<\/p>\n\n\n\n{\n "applinks": {\n "details": [\n {\n "appIDs": ["TEAMID.com.yourcompany.yourapp"],\n "components": [\n { "\/": "\/products\/*" },\n { "\/": "\/offers\/*" },\n { "\/": "\/referral\/*" }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\n3. Handle the URL in AppDelegate<\/h3>\n\n\n\n
AppDelegate.swift<\/code> already includes the Universal Links handler. Verify it exists:<\/p>\n\n\n\nfunc application(_ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {\n return CAPBridge.handleContinueActivity(userActivity, restorationHandler: restorationHandler)\n}\n<\/code><\/pre>\n\n\n\nAndroid Configuration<\/h2>\n\n\n\n
1. Intent Filters<\/h3>\n\n\n\n
android\/app\/src\/main\/AndroidManifest.xml<\/code>:<\/p>\n\n\n\n<activity\n android:name="com.yourcompany.yourapp.MainActivity"\n android:exported="true">\n\n <!-- Existing intent filters... -->\n\n <!-- App Links -->\n <intent-filter android:autoVerify="true">\n <action android:name="android.intent.action.VIEW" \/>\n <category android:name="android.intent.category.DEFAULT" \/>\n <category android:name="android.intent.category.BROWSABLE" \/>\n <data android:scheme="https"\n android:host="yourdomain.com"\n android:pathPrefix="\/products" \/>\n <data android:scheme="https"\n android:host="yourdomain.com"\n android:pathPrefix="\/offers" \/>\n <data android:scheme="https"\n android:host="yourdomain.com"\n android:pathPrefix="\/referral" \/>\n <\/intent-filter>\n<\/activity>\n<\/code><\/pre>\n\n\n\n2. assetlinks.json<\/h3>\n\n\n\n
https:\/\/yourdomain.com\/.well-known\/assetlinks.json<\/code>:<\/p>\n\n\n\n[\n {\n "relation": ["delegate_permission\/common.handle_all_urls"],\n "target": {\n "namespace": "android_app",\n "package_name": "com.yourcompany.yourapp",\n "sha256_cert_fingerprints": [\n "YOUR_SIGNING_KEY_FINGERPRINT"\n ]\n }\n }\n]\n<\/code><\/pre>\n\n\n\n# Debug key\nkeytool -list -v -keystore ~\/.android\/debug.keystore -alias androiddebugkey -storepass android\n\n# Release key (Play App Signing)\n# Find in Google Play Console > Setup > App signing\n<\/code><\/pre>\n\n\n\nJavaScript-Side Handling<\/h2>\n\n\n\n
Using the App Plugin<\/h3>\n\n\n\n
@capacitor\/app<\/code> plugin provides the appUrlOpen<\/code> event:<\/p>\n\n\n\nimport { App } from '@capacitor\/app';\nimport { Router } from '@angular\/router'; \/\/ or your framework's router\n\n\/\/ Listen for deep link opens\nApp.addListener('appUrlOpen', (event) => {\n console.log('Deep link URL:', event.url);\n\n const url = new URL(event.url);\n const path = url.pathname;\n const params = Object.fromEntries(url.searchParams);\n\n \/\/ Route to the correct page\n handleDeepLink(path, params);\n});\n\nfunction handleDeepLink(path: string, params: Record<string, string>) {\n \/\/ Match routes\n const productMatch = path.match(\/^\\\/products\\\/([^\/]+)$\/);\n if (productMatch) {\n router.navigate(['\/product', productMatch[1]], { queryParams: params });\n return;\n }\n\n const offerMatch = path.match(\/^\\\/offers\\\/([^\/]+)$\/);\n if (offerMatch) {\n router.navigate(['\/offer', offerMatch[1]], { queryParams: params });\n return;\n }\n\n const referralMatch = path.match(\/^\\\/referral\\\/([^\/]+)$\/);\n if (referralMatch) {\n router.navigate(['\/referral', referralMatch[1]], { queryParams: params });\n return;\n }\n\n \/\/ Default: go home\n router.navigate(['\/']);\n}\n<\/code><\/pre>\n\n\n\nHandling Cold Start vs Warm Start<\/h3>\n\n\n\n
\n
appUrlOpen<\/code> event fires.<\/li>\n<\/ul>\n\n\n\nimport { App } from '@capacitor\/app';\n\nasync function initializeApp() {\n \/\/ Check if the app was launched from a deep link\n const launchUrl = await App.getLaunchUrl();\n if (launchUrl?.url) {\n console.log('App launched from deep link:', launchUrl.url);\n handleDeepLink(new URL(launchUrl.url).pathname, {});\n }\n\n \/\/ Listen for subsequent deep links (warm start)\n App.addListener('appUrlOpen', (event) => {\n handleDeepLink(new URL(event.url).pathname, {});\n });\n}\n<\/code><\/pre>\n\n\n\nWith Angular Router<\/h3>\n\n\n\n
import { Injectable } from '@angular\/core';\nimport { Router } from '@angular\/router';\nimport { App } from '@capacitor\/app';\n\n@Injectable({ providedIn: 'root' })\nexport class DeepLinkService {\n constructor(private router: Router) {}\n\n initialize() {\n \/\/ Cold start\n App.getLaunchUrl().then(result => {\n if (result?.url) this.route(result.url);\n });\n\n \/\/ Warm start\n App.addListener('appUrlOpen', event => {\n this.route(event.url);\n });\n }\n\n private route(urlString: string) {\n const url = new URL(urlString);\n \/\/ Angular router can handle the path directly\n this.router.navigateByUrl(url.pathname + url.search);\n }\n}\n<\/code><\/pre>\n\n\n\nWith React (Capacitor + React)<\/h3>\n\n\n\n
import { useEffect } from 'react';\nimport { useNavigate } from 'react-router-dom';\nimport { App } from '@capacitor\/app';\n\nfunction useDeepLinks() {\n const navigate = useNavigate();\n\n useEffect(() => {\n \/\/ Cold start\n App.getLaunchUrl().then(result => {\n if (result?.url) {\n const url = new URL(result.url);\n navigate(url.pathname + url.search);\n }\n });\n\n \/\/ Warm start\n const listener = App.addListener('appUrlOpen', event => {\n const url = new URL(event.url);\n navigate(url.pathname + url.search);\n });\n\n return () => {\n listener.then(l => l.remove());\n };\n }, [navigate]);\n}\n<\/code><\/pre>\n\n\n\nTesting<\/h2>\n\n\n\n
iOS<\/h3>\n\n\n\n
# Test on iOS Simulator\nxcrun simctl openurl booted "https:\/\/yourdomain.com\/products\/123"\n\n# If the app opens and navigates to the product page, it works\n<\/code><\/pre>\n\n\n\nAndroid<\/h3>\n\n\n\n
# Test on connected device\/emulator\nadb shell am start -a android.intent.action.VIEW \\\n -d "https:\/\/yourdomain.com\/products\/123" \\\n -c android.intent.category.BROWSABLE\n<\/code><\/pre>\n\n\n\nIn the Browser (Development)<\/h3>\n\n\n\n
http:\/\/localhost:8100\/products\/123\n<\/code><\/pre>\n\n\n\nCommon Issues<\/h2>\n\n\n\n