Universal links on iOS: opening your app from a link, safely
How iOS routes HTTPS URLs into your app, the two-way domain association that makes it trustworthy, and Apple's warning about validating link input.
When someone taps a link to your site on an iPhone, you usually want your app to open that content directly - not Safari, and not a redirect trampoline. That is what universal links do: ordinary HTTPS URLs that iOS routes straight into your app when it is installed. They are also one of the most commonly misconfigured parts of an app launch.
This guide follows Apple's own developer documentation, checked 19 November 2026.
What a universal link is (and is not)
A universal link is a normal HTTPS URL on a domain you own. When a user activates it, iOS checks whether an installed app is associated with that domain and path; if so, the system launches your app and hands it the URL. If not, the same URL opens in the browser - which is why the web page must always work as the fallback. Custom URL schemes (myapp://) by contrast fail hard when the app is missing and can be claimed by any app; universal links are verified against your domain.
The two halves of the setup
Apple's documentation breaks support into two steps:
- Create the two-way association. Your app declares the domains it handles (the associated domains entitlement), and your website hosts an association file that declares which apps may open which paths. iOS verifies both sides against each other, which is what stops a third-party app from hijacking your links. Apple documents the details under "Supporting associated domains".
- Handle the incoming activity. When the system opens your app from a universal link, your app delegate receives an NSUserActivity object with its activity type set to browsing-the-web, and the URL in the object's webpageURL property. Apple's sample code extracts the URL with NSURLComponents, checks the path and query items it needs, and returns false when they are missing - so the system can fall back gracefully instead of dropping the user on a broken screen.
The security warning teams skip
Apple's own page carries a warning that deserves to be treated as a requirement: universal links are a potential attack vector into your app. Validate all URL parameters and discard malformed URLs; limit link-driven actions to ones that cannot risk user data - a universal link should never directly delete content or expose sensitive information; and include improperly formatted URLs in your test cases. A link is untrusted input, exactly like a form field.
Failure modes to test before launch
- The web fallback. Uninstall the app and tap the link: the page must load and be useful, not a 404 or a bare "download our app" interstitial.
- Malformed and hostile URLs. Missing parameters, wrong types, absurd lengths, path traversal attempts - your handler should reject them and return false.
- Logged-out and cold-start states. The app may launch fresh, not resume: the link target must survive authentication and first-run flows.
- The association file itself. Serve it over HTTPS, at the documented location, with correct content type and no redirects; a mis-served file silently breaks routing and is painful to diagnose because caching hides fixes.
Related: allowlist-testing redirect targets covers the same untrusted-URL discipline on the web side, and ASO basics covers how your store listing and site work together.
Sources
- Apple Developer Documentation: Supporting universal links in your app (checked 19 November 2026): https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app
Drafted with AI assistance from this source. Entitlement and association-file specifics change between iOS releases; follow Apple's current "Supporting associated domains" documentation for the exact file format and hosting rules.