Universal Links are Apple's mechanism for opening your app when a user taps an HTTPS link to your domain. Unlike custom URL schemes, Universal Links are secure (only you can claim your domain), reliable (they fall back to the web if the app isn't installed), and don't show a disambiguation dialog.<\/p>\n\n\n\n
This guide focuses on the iOS-specific setup for Universal Links in React Native. For the full cross-platform setup (including Android App Links), see React Native Deep Linking: Complete Setup Tutorial<\/a>. For Universal Links fundamentals, see Universal Links: Everything You Need to Know<\/a>.<\/p>\n\n\n\n The flow when a user taps a Universal Link:<\/p>\n\n\n\n The "claim" happens through two pieces:<\/p>\n\n\n\n Your web server (or deep linking platform) must serve a JSON file at:<\/p>\n\n\n\n The file content:<\/p>\n\n\n\n If using Tolinku, the AASA file is served automatically when you configure your Appspace with your Team ID and Bundle ID.<\/p>\n\n\n\n Apple caches AASA files through their CDN. When you first deploy or update your AASA, it can take up to 24-48 hours for Apple to re-fetch it. Check what Apple currently has cached:<\/p>\n\n\n\n To request a re-crawl, use Apple's Search Validation tool<\/a> and enter your domain.<\/p>\n\n\n\n This generates (or updates) the If your links come from multiple domains:<\/p>\n\n\n\n For development and testing, you can use the This tells iOS to fetch the AASA file directly from your server instead of Apple's CDN, which is useful during development when you're frequently updating the file.<\/p>\n\n\n\n React Native's If your app uses Universal Links arrive as full HTTPS URLs:<\/p>\n\n\n\n Check the AASA file:<\/strong><\/p>\n\n\n\n Check the entitlement:<\/strong><\/p>\n\n\n\n Check the device:<\/strong><\/p>\n\n\n\n This happens when:<\/p>\n\n\n\n Different apps handle Universal Links differently:<\/p>\n\n\n\n If links work when the app is backgrounded but not when launching the app fresh:<\/p>\n\n\n\n For Android App Links (the Android equivalent), see the Android section in React Native Deep Linking<\/a>. For the Tolinku SDK, see the React Native SDK docs<\/a>. For deep linking features, see Tolinku deep linking<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":" Configure Universal Links for React Native apps. Handle iOS-specific setup, AppDelegate configuration, and link handling in JavaScript.<\/p>\n","protected":false},"author":2,"featured_media":898,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Universal Links in React Native: Complete Guide","rank_math_description":"Configure Universal Links for React Native apps. Handle iOS-specific setup, AppDelegate configuration, and link handling in JavaScript.","rank_math_focus_keyword":"React Native universal links","rank_math_canonical_url":"","rank_math_facebook_title":"","rank_math_facebook_description":"","rank_math_facebook_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-react-native-universal-links.png","rank_math_facebook_image_id":"","rank_math_twitter_title":"","rank_math_twitter_description":"","rank_math_twitter_image":"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/og-react-native-universal-links.png","footnotes":""},"categories":[15],"tags":[76,122,20,24,71,69,56,22],"class_list":["post-899","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-engineering","tag-aasa","tag-apple","tag-deep-linking","tag-ios","tag-javascript","tag-mobile-development","tag-react-native","tag-universal-links"],"_links":{"self":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/899","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/comments?post=899"}],"version-history":[{"count":1,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/899\/revisions"}],"predecessor-version":[{"id":900,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/posts\/899\/revisions\/900"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media\/898"}],"wp:attachment":[{"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/media?parent=899"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/categories?post=899"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/tolinku.com\/blog\/wp-json\/wp\/v2\/tags?post=899"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}How Universal Links Work<\/h2>\n\n\n\n
\n
\n
Step 1: Apple App Site Association (AASA) File<\/h2>\n\n\n\n
https:\/\/go.yourapp.com\/.well-known\/apple-app-site-association\n<\/code><\/pre>\n\n\n\n{\n "applinks": {\n "apps": [],\n "details": [\n {\n "appIDs": ["TEAMID.com.yourapp.bundleid"],\n "components": [\n { "\/": "\/product\/*" },\n { "\/": "\/invite\/*" },\n { "\/": "\/promo\/*" }\n ]\n }\n ]\n }\n}\n<\/code><\/pre>\n\n\n\nAASA Requirements<\/h3>\n\n\n\n
\n
Content-Type: application\/json<\/code><\/li>\nVerify the AASA<\/h3>\n\n\n\n
# Check accessibility\ncurl -I https:\/\/go.yourapp.com\/.well-known\/apple-app-site-association\n\n# Check content\ncurl https:\/\/go.yourapp.com\/.well-known\/apple-app-site-association | python3 -m json.tool\n<\/code><\/pre>\n\n\n\nApple's CDN Cache<\/h3>\n\n\n\n
curl "https:\/\/app-site-association.cdn-apple.com\/a\/v1\/go.yourapp.com"\n<\/code><\/pre>\n\n\n\nStep 2: Associated Domains Entitlement<\/h2>\n\n\n\n
In Xcode<\/h3>\n\n\n\n
\n
ios\/YourApp.xcworkspace<\/code> in Xcode<\/li>\napplinks:go.yourapp.com<\/code><\/li>\n<\/ol>\n\n\n\nYourApp.entitlements<\/code> file:<\/p>\n\n\n\n<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-\/\/Apple\/\/DTD PLIST 1.0\/\/EN" "http:\/\/www.apple.com\/DTDs\/PropertyList-1.0.dtd">\n<plist version="1.0">\n<dict>\n <key>com.apple.developer.associated-domains<\/key>\n <array>\n <string>applinks:go.yourapp.com<\/string>\n <\/array>\n<\/dict>\n<\/plist>\n<\/code><\/pre>\n\n\n\nMultiple Domains<\/h3>\n\n\n\n
<array>\n <string>applinks:go.yourapp.com<\/string>\n <string>applinks:links.yourapp.com<\/string>\n<\/array>\n<\/code><\/pre>\n\n\n\nDeveloper Mode (iOS 14+)<\/h3>\n\n\n\n
?mode=developer<\/code> suffix:<\/p>\n\n\n\n<string>applinks:go.yourapp.com?mode=developer<\/string>\n<\/code><\/pre>\n\n\n\nStep 3: AppDelegate Configuration<\/h2>\n\n\n\n
RCTLinkingManager<\/code> bridges the native Universal Link callback to JavaScript.<\/p>\n\n\n\nFor Objective-C AppDelegate (AppDelegate.mm)<\/h3>\n\n\n\n
#import <React\/RCTLinkingManager.h>\n\n@implementation AppDelegate\n\n\/\/ Handle Universal Links\n- (BOOL)application:(UIApplication *)application\n continueUserActivity:(NSUserActivity *)userActivity\n restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler\n{\n return [RCTLinkingManager application:application\n continueUserActivity:userActivity\n restorationHandler:restorationHandler];\n}\n\n\/\/ Handle custom URL schemes (optional, but recommended as fallback)\n- (BOOL)application:(UIApplication *)application\n openURL:(NSURL *)url\n options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options\n{\n return [RCTLinkingManager application:application openURL:url options:options];\n}\n\n@end\n<\/code><\/pre>\n\n\n\nFor Swift AppDelegate (AppDelegate.swift)<\/h3>\n\n\n\n
import React\n\n@main\nclass AppDelegate: UIResponder, UIApplicationDelegate {\n\n func application(\n _ application: UIApplication,\n continue userActivity: NSUserActivity,\n restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void\n ) -> Bool {\n return RCTLinkingManager.application(\n application,\n continue: userActivity,\n restorationHandler: restorationHandler\n )\n }\n\n func application(\n _ app: UIApplication,\n open url: URL,\n options: [UIApplication.OpenURLOptionsKey: Any] = [:]\n ) -> Bool {\n return RCTLinkingManager.application(app, open: url, options: options)\n }\n}\n<\/code><\/pre>\n\n\n\nSceneDelegate (iOS 13+)<\/h3>\n\n\n\n
UISceneDelegate<\/code> (the default for newer React Native projects):<\/p>\n\n\n\n\/\/ SceneDelegate.m\n#import <React\/RCTLinkingManager.h>\n\n- (void)scene:(UIScene *)scene\n continueUserActivity:(NSUserActivity *)userActivity {\n [RCTLinkingManager application:[UIApplication sharedApplication]\n continueUserActivity:userActivity\n restorationHandler:^(NSArray<id<UIUserActivityRestoring>> * _Nullable restorableObjects) {\n }];\n}\n\n- (void)scene:(UIScene *)scene\n openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {\n for (UIOpenURLContext *context in URLContexts) {\n [RCTLinkingManager application:[UIApplication sharedApplication]\n openURL:context.URL\n options:@{}];\n }\n}\n<\/code><\/pre>\n\n\n\nStep 4: JavaScript Link Handling<\/h2>\n\n\n\n
Receiving Universal Links<\/h3>\n\n\n\n
import { Linking } from 'react-native';\n\n\/\/ Cold start: app was launched by the link\nuseEffect(() => {\n Linking.getInitialURL().then((url) => {\n if (url) {\n handleUniversalLink(url);\n }\n });\n}, []);\n\n\/\/ Warm start: app was already running\nuseEffect(() => {\n const subscription = Linking.addEventListener('url', ({ url }) => {\n handleUniversalLink(url);\n });\n return () => subscription.remove();\n}, []);\n<\/code><\/pre>\n\n\n\nParsing Universal Link URLs<\/h3>\n\n\n\n
function handleUniversalLink(url) {\n const parsed = new URL(url);\n\n \/\/ Verify it's your domain\n if (parsed.hostname !== 'go.yourapp.com') {\n return;\n }\n\n const path = parsed.pathname;\n const params = Object.fromEntries(parsed.searchParams);\n\n \/\/ Route to the correct screen\n if (path.startsWith('\/product\/')) {\n const id = path.split('\/')[2];\n navigation.navigate('Product', { id });\n } else if (path.startsWith('\/invite\/')) {\n const code = path.split('\/')[2];\n navigation.navigate('Invite', { code });\n } else {\n \/\/ Unknown path: navigate to home or show not-found\n navigation.navigate('Home');\n }\n}\n<\/code><\/pre>\n\n\n\nTroubleshooting<\/h2>\n\n\n\n
Universal Links Don't Open the App<\/h3>\n\n\n\n
\n
https:\/\/yourdomain\/.well-known\/apple-app-site-association<\/code>?<\/li>\nContent-Type: application\/json<\/code>?<\/li>\nappID<\/code> match your Team ID + Bundle ID exactly?<\/li>\ncomponents<\/code> (or paths<\/code> for the older format) correct?<\/li>\n<\/ul>\n\n\n\n\n
https:\/\/<\/code>, no trailing slash)<\/li>\n\n
Universal Links Open Safari Instead<\/h3>\n\n\n\n
\n
Universal Links Work in Some Apps but Not Others<\/h3>\n\n\n\n
\n
SFSafariViewController<\/code> or WKWebView<\/code>, which have different Universal Link behavior<\/li>\n<\/ul>\n\n\n\nCold Start Links Not Received<\/h3>\n\n\n\n
\n
continueUserActivity<\/code> (or the SceneDelegate equivalent) is called before RCTBridge<\/code> finishes initialization<\/li>\nLinking.getInitialURL()<\/code> is called early in your app's JavaScript entry point<\/li>\nTesting Checklist<\/h2>\n\n\n\n
\/.well-known\/apple-app-site-association<\/code><\/li>Content-Type: application\/json<\/code><\/li>appIDs<\/code> matches Team ID + Bundle ID<\/li>applinks:yourdomain<\/code><\/li>continueUserActivity<\/code> implemented in AppDelegate\/SceneDelegate<\/li>Linking.getInitialURL()<\/code><\/li>Linking.addEventListener<\/code><\/li>