Universal Links iOS: Complete Setup & Debugging Guide (2026)

Universal Links iOS: Complete Setup & Debugging Guide (2026)

Universal links ios are standard HTTPS URLs that open your native app directly when it is installed and fall back to a normal webpage in Safari when it is not, with no custom URL scheme and no app store interstitial in between. Apple introduced them in iOS 9 to replace custom schemes with a web-verified, tamper-resistant way to deep link into apps.

This guide covers how apple universal links actually work under the hood, the exact files and entitlements you need to configure them, a Swift handler you can drop into your AppDelegate, and the four problems that break universal links in ios more often than anything else.

A universal link is a regular https:// URL that both your website and your iOS app agree to handle, verified through a file hosted on your domain. Unlike custom schemes such as myapp://, the link works everywhere, in a browser, an email client, or a text message, because it is a normal web address first.

When someone taps https://yourdomain.com/products/shoes, iOS checks whether an installed app has claimed that domain. If it has, the app opens straight to that product page. If not, Safari opens the same URL as a normal webpage. No error message, no "install our app" dead end, no redirect chain.

  • Opens directly in your iOS app if it is installed

  • Opens in Safari if the app is not installed

  • Works without any app store redirect prompt in between

Platforms like Smler's deep linking solution build on top of this behaviour to add analytics and branded short domains without breaking the link's ability to open the app.

A universal link ios implementation rests on three pieces: an Apple App Site Association (AASA) file hosted on your server, an Associated Domains entitlement declared inside your app, and a handler method that receives the URL once iOS decides to open your app instead of Safari.

1. The Apple App Site Association file

The AASA file is a JSON file you copy into the Smler dashboard, not inside the app, at one of these two locations:

Code
https://yourdomain.com/.well-known/apple-app-site-association
https://yourdomain.com/apple-app-site-association

It tells iOS which app, and which paths on your domain, are allowed to open that app instead of the browser:

Code
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": ["TEAMID.com.yourcompany.yourapp"],
        "paths": [
          "/products/*",
          "/blog/*"
        ]
      }
    ]
  }
}

Requirements that trip people up:

  • Served over HTTPS, not HTTP

  • Content-Type header of application/json

  • No redirects, the file must respond at the exact URL with a 200 status

  • File size under 128 KB

2. The Associated Domains entitlement

Inside Xcode, you add the Associated Domains capability to your app's target and list every domain that should trigger your app, prefixed with applinks::

Code
applinks:yourdomain.com
applinks:www.yourdomain.com

This entitlement is what tells iOS, at install or update time, to go fetch and cache the AASA file from each listed domain. Without it, iOS never looks for the file at all and every link from that domain opens in Safari regardless of what the AASA file says. Apple's associated domains documentation covers the entitlement syntax in full.

When iOS opens your app from a universal link, it does not call your scheme handler, it calls a dedicated method on your app delegate with the full URL:

Code
func application(_ application: UIApplication,
                  continue userActivity: NSUserActivity,
                  restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {

    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }

    // Hit the Smler endpoint to resolve the short URL to a long URL,
    // then route to the matching screen in your app
    handleIncomingURL(url)

    return true
}

Your job inside handleIncomingURL is to hit the Smler endpoint to get the corresponding long URL for this short URL. Using that, you can open the specific screen in app. If the path does not match anything you recognise, fall back to your app's home screen rather than doing nothing.

What happens on a tap, end to end:

  1. iOS checks whether any installed app has claimed the tapped domain via Associated Domains

  2. It matches the URL's path against the patterns cached from that domain's AASA file

  3. If there is a match and the app is installed, iOS opens the app and calls the delegate method above

  4. If there is no match, or the app is not installed, Safari opens the URL as a normal webpage

Note that iOS only downloads and caches the AASA file when the app is installed or updated, not on every tap. That caching is also why changes to the file do not show up instantly, more on that in the troubleshooting section below.

Universal links are Apple's iOS-only implementation of verified HTTPS deep linking; Android App Links are the equivalent on Android, using a similar verified-domain model; custom URL schemes (myapp://) are an older, unverified approach available on both platforms but without domain ownership checks. If you are building for both platforms, you need both universal links and App Links configured separately, they do not share a single file format.

ApproachPlatformDomain verifiedWorks as a web link
Universal LinksiOSYes (AASA file)Yes
App LinksAndroidYes (assetlinks.json)Yes
Custom URL SchemeiOS and AndroidNoNo

For a full side-by-side comparison, including setup differences, see the Universal Links vs App Links guide.

Setting up a universal link ios implementation takes nine steps, from writing the AASA file to verifying it fires on a real device. Skipping the "test from an external app" step is the most common reason developers think it is broken when it is actually working.

  1. Write your AASA file with your Team ID, bundle identifier, and the exact paths you want the app to claim

  2. Host the file at https://yourdomain.com/.well-known/apple-app-site-association with a valid SSL certificate, no redirects

  3. Add the Associated Domains capability in Xcode's Signing & Capabilities tab

  4. List your domains in the format applinks:yourdomain.com

  5. Implement the delegate method shown above to receive and route the incoming URL

  6. Build and install a fresh copy of the app on a physical test device (universal links are unreliable on simulators)

  7. Tap the link from an external source such as Notes, Messages, or Mail, never from inside Safari's own address bar or the same domain

  8. Validate the file's format with a dedicated tool before assuming the code is at fault

  9. Monitor real-world performance once you ship, to see how often links actually open the app versus the browser

Universal links in ios usually break for one of four reasons: the AASA file isn't reachable, the Associated Domains entitlement is missing or stale, the long-press menu doesn't show the app option, or iOS is still serving a cached version of an old AASA file. Each has a distinct, checkable fix.

1. The AASA file isn't being downloaded

This is the most common issue. Verify:

  • The file is accessible at the correct URL with no typos in the path

  • Your server returns it over HTTPS with a valid SSL certificate

  • No redirects are happening between the request and the file

  • The Content-Type header is set correctly

Check your file's format and headers with Smler's AASA validator before digging into app code.

If universal links open Safari rather than your app, check:

  • The Associated Domains entitlement is correctly configured in Xcode

  • You have installed a fresh build after adding Associated Domains, old installs won't re-check it

  • The URL's path actually matches a pattern in your AASA file

  • You are testing from an external source, not from Safari's own address bar or the same domain

3. The long-press menu shows the wrong options

When users long-press a universal link, they should see an option to open it in your app. If that option is missing, iOS has not recognised the link as a universal link at all, which almost always traces back to the AASA file or the Associated Domains configuration rather than your in-app routing code.

4. Changes to the AASA file don't take effect

iOS caches the AASA file and does not re-check it on every tap. To force an update:

  • Uninstall and reinstall the app on test devices

  • For production users, ship an app update through the App Store, which forces a re-download

  • Allow up to 24 hours for Apple's CDN to propagate the change everywhere

For a systematic way to confirm a link is actually firing on device, walk through the guide to testing deep links on iOS.

What Happens When the App Isn't Installed?

Universal links only handle the case where your app is already on the device, they do nothing for a user who clicks the link, lands on your website, and installs the app later with no memory of what they originally wanted. That gap is covered by deferred deep linking, which remembers the intended destination through the App Store install and reopens the app to that exact content afterward.

For a complete mobile strategy you typically need both. Smler's deferred deep linking capabilities are built to work alongside universal links rather than replace them, and the iOS integration guide walks through wiring both into the same Swift codebase.

Universal links have to use your own domain, which creates friction when you need a short link for SMS, want per-link analytics, or are running the same campaign across several channels. An intelligent URL shortener solves this without breaking the link's ability to open your app.

Smler's platform is built specifically to sit in front of universal links, letting you:

If you are moving off Firebase Dynamic Links, Smler also documents a Firebase Dynamic Links migration path now that Firebase has shut the service down.

1. Support both www and non-www domains

Users may land on https://example.com or https://www.example.com. Add both as separate applinks: entries and host an AASA file at each.

2. Use specific path patterns

Claiming everything with "*" invites conflicts. Specify exact patterns like "/products/*" so you keep control over which links actually open the app.

3. Implement a sensible fallback

If a deep link's parameters are missing or malformed, route to a default screen. A crash on a bad link is worse than no deep link at all.

4. Test across iOS versions

Universal link behaviour has shifted across releases. Test on the current iOS version and on the oldest version your app still supports.

Track how often links are actually opening the app versus falling back to the browser. Smler's analytics dashboard surfaces this split per link.

Apple introduced universal links at WWDC 2015 as part of iOS 9, alongside Spotlight indexing and Safari View Controller, to fix the two big problems with custom URL schemes: any app could register any scheme, and there was no way to verify the app claiming a scheme actually owned the matching domain. Requiring domain ownership through the AASA file solved both at once, and the core mechanism has stayed the same since, with iOS 17 and 18 mainly improving caching speed and Xcode's debugging tools around it.

Frequently asked questions

What are universal links in iOS?

Universal links in iOS are standard HTTPS URLs that open your native app directly when it's installed and fall back to Safari when it isn't. They require a hosted AASA file and an Associated Domains entitlement, which together let iOS verify your app actually owns the domain before opening it.

How do apple universal links differ from custom URL schemes?

Apple universal links are verified HTTPS URLs tied to a domain you provably own, while custom schemes like myapp:// can be registered by any app with no ownership check. Universal links also work as normal web links everywhere; custom schemes break outside the app context.

Why do my universal links open Safari instead of my app?

The most common causes are a missing or misconfigured Associated Domains entitlement, testing without a fresh build after adding it, a URL path that doesn't match any pattern in your AASA file, or tapping the link from within Safari itself instead of an external app like Messages.

Do universal links work if the app isn't installed?

Yes, but only as a graceful fallback: the user will be redirected to the App Store or Play Store based on the device they are using. Universal links do not remember the intended destination through an App Store install, that requires deferred deep linking layered on top.

How long does it take for AASA file changes to show up?

iOS only downloads the AASA file at install or update time and caches it afterward, so edits don't apply instantly. On test devices, uninstall and reinstall the app; in production, ship an app update and allow roughly 24 to 48 hours for Apple's CDN to propagate the change.

Next in this guideHow to Test Deep Links on iOS: Complete Guide 2026