Universal Links and App Links explained: a setup guide for indie app makers

The two side by side

Neither one sends people to the store when the app is missing. For that you need a smart link in front, or a web page with store badges. And neither one remembers where someone was going after they install. That's deferred deep linking, a separate problem.

Set up Universal Links

1. Publish the file at https://yourdomain/.well-known/apple-app-site-association, with no file extension. Apple requires HTTPS with a valid certificate and no redirects.
2. List your app and paths. Each appIDs entry is your Team ID, a dot, and your bundle ID. The components list says which paths open the app. Put exclusions first.
3. Add the entitlement. In Xcode, under Signing and Capabilities, add Associated Domains with applinks:yourdomain. Use the domain only: no https, no path, no trailing slash. Each subdomain needs its own entry and its own file. See the entitlement reference.
4. Handle the link in your app. UIKit apps receive an NSUserActivity with the URL in webpageURL. SwiftUI apps get it through onOpenURL. Validate the URL before you act on it. Apple covers both in Supporting universal links in your app.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.yourapp.ios"],
        "components": [
          { "/": "/account/*", "exclude": true },
          { "/": "/*" }
        ]
      }
    ]
  }
}

Since iOS 14, phones don't fetch this file from your server. Apple's CDN does, within 24 hours of a change, and devices check for updates about once a week after the app is installed. While you develop, add ?mode=developer to the entitlement to bypass the CDN on a device in developer mode.

Set up App Links

1. Publish the file at https://yourdomain/.well-known/assetlinks.json, served as application/json over HTTPS with no 301 or 302 redirects.
2. Use the right fingerprint. If Google Play signs your app, the fingerprint from your local keystore usually won't match what phones see. Copy the SHA-256 from Play Console, under App signing. It also shows a ready-made assetlinks.json snippet.
3. Add the intent filter with android:autoVerify="true", the VIEW action, the DEFAULT and BROWSABLE categories, and your https host. Don't add other schemes to the same filter, because that prevents verification.
4. Check verification with adb shell pm get-app-links com.yourapp.android. The domain should show as verified. Google's Statement List tester checks the file from the outside.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourapp.android",
    "sha256_cert_fingerprints": ["14:6D:E9:83:...:5E"]
  }
}]

<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" android:host="links.yourapp.com" />
</intent-filter>

Verification matters more since Android 12. If your app isn't verified for a domain, a web link opens in the user's default browser instead of offering your app. Google's verification guide has the adb commands to reset and re-run it while you test.

Traps that make links open the browser

• Typing the URL. On iPhone, a URL typed into the browser's address bar never opens the app. Test by pasting the link into Notes and tapping it.
• Same-domain links. If someone is already on your website in Safari and taps a link to the same domain, iOS keeps them in Safari. Links from a different domain open the app.
• Redirects in front of the file. Apple and Google both refuse the file if its URL redirects, for example from the bare domain to www. Serve it directly on the exact host your links use.
• In-app browsers. Links tapped inside Instagram, TikTok or other social apps often stay in that app's browser. Test there separately.
• The wrong build. The entitlement or intent filter has to be in the build that's installed, not only in your project.

If your file checks out but iPhones still open Safari, our Universal Links troubleshooting checklist goes through the next checks in order.

If you'd rather not host the files

You need a domain you control to publish these files. If your marketing site runs on a builder that won't serve files from /.well-known/, or you don't want to maintain them, a link service can host them for you.

On URX, Pro publishes apple-app-site-association for urx.si. Add your Team ID and bundle ID to your project, add applinks:urx.si to your app, and your urx.si/yourapp links open the app on iPhone. App Links need a domain your app can verify on its own, so they work on a custom domain such as links.yourapp.com, which comes with Growth. URX serves both files there. The link's Deep linking tab shows what Apple and Google see.

Whatever you use, the free AASA validator checks your file and Apple's CDN copy. To start with store routing and add deep links later, claim a free link. The deep-linking page explains each link type.