📆 ⏱️ 5 min de lectura

Let’s start from the beginning: What is a Universal Link?

A Universal Link is a way to connect web URLs directly with your iOS app. When a user taps a link pointing to your domain (for example, from a message, an email, or any other app), iOS can open your app directly instead of Safari, creating a much smoother and more native user experience.

It’s like having deep linking, but better: it works from anywhere in the system and doesn’t require the user to confirm anything.

Universal Links work through a special file that Apple looks for on your web server: the apple-app-site-association file. This file tells iOS which URLs from your domain should open your app.

The apple-app-site-association (AASA) file

The apple-app-site-association file is a JSON file that maps your domain’s URLs that you want to open your iOS app. In other words, you’re telling iOS: “when a user taps a link that starts with /test, for example, open my app instead of Safari”.

Practical example: If you configure in the file that all URLs starting with /test should open the app, then:

  • âś… https://yourdomain.com/test/product-123 → Opens your app
  • âś… https://yourdomain.com/test/user/456 → Opens your app
  • ❌ https://yourdomain.com/other-path → Opens in Safari (not mapped)

Important: The apple-app-site-association file only defines which URLs open the app. Once the app opens with a Universal Link, how the app handles what to do with that URL is a completely separate matter and agnostic to this configuration problem. The app will receive the URL and you decide how to handle it in your Swift code.

⚠️ The file is completely public: This file must be publicly accessible on your server. It doesn’t contain sensitive information, it only maps which URLs from your domain should open your app. Anyone can access it from a browser.

File location

Apple allows two locations for the file:

  1. At the domain root: https://yourdomain.com/apple-app-site-association
  2. In .well-known: https://yourdomain.com/.well-known/apple-app-site-association

Recommendation: Always use .well-known because:

  • It’s the web standard (RFC 8615)
  • Works equally in production and test environments
  • Keeps files organized
  • Avoids conflicts with your application routes

Apple’s CDN

When Apple detects your apple-app-site-association file on a public domain, it downloads and saves it to its own CDN (Content Delivery Network). This means that:

  1. Apple accesses the file first: iOS tries to get the file from Apple’s CDN before your server, making it very fast
  2. Works in production: On accessible public domains, Apple can download and cache it correctly
  3. Problems in private environments: If your domain is behind a VPN or in a private environment, Apple’s servers can’t access the file, so they can’t save it to their CDN. That’s why in test environments you need to use developer mode (I’ll explain this in the next article)

File structure

The file must be valid JSON and have this basic structure:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAM_ID.com.yourcompany.yourapp"],
        "components": [
          {
            "/": "/test/*",
            "comment": "Matches any URL with path that starts with /test/"
          }
        ]
      }
    ]
  }
}

Important elements:

  • TEAM_ID: Your Apple Developer Team ID
  • com.yourcompany.yourapp: Your exact Bundle Identifier
  • components: Maps the URLs you want to open your app. In the example, "/": "/test/*" means all URLs starting with /test will open your app.

⚠️ Critical: The file should NOT have a .json extension - it must be called exactly apple-app-site-association

What do you need for them to work?

For Universal Links to work, you need two things:

  1. The apple-app-site-association file on your web server that maps the URLs
  2. Configure Associated Domains in Xcode to tell iOS that your app can handle links from your domain.

Associated Domains is an iOS capability that tells the system which domains your app can handle. Without this configuration, iOS won’t know that your app can open links from your domain. In Signing & Capabilities, add in Associated Domains:

applinks:yourdomain.com

Safari has special behavior

Safari has special behavior with Universal Links:

  • Links from the same domain: If you tap a Universal Link within Safari pointing to the same domain as the current page, iOS maintains the browsing context and opens the link in Safari. Apple assumes that if you’re browsing in Safari, you want to continue in the browser.

  • Links from different domain: If the Universal Link points to a different domain, iOS will open your app (if installed).

  • Copy and paste URLs: If you copy a URL and paste it into Safari’s address bar, Apple interprets that your intention is to continue browsing in the browser, not to open the app.

Chrome as default browser (iOS 14+)

Since iOS 14, Apple allows configuring third-party browsers (like Chrome, Firefox, Edge, etc.) as the default browser. However, Universal Links are mainly supported by Safari. If Chrome (or another browser) is configured as default, Universal Links may not work automatically.

Summary

Universal Links are a powerful way to connect your iOS app with web URLs. Advantages of Universal Links:

  • âś… Work from any system app (Messages, Mail, WhatsApp, etc.)
  • âś… Don’t require user confirmation
  • âś… If the app isn’t installed, the link opens in Safari
  • âś… Significantly improve user experience

Limitations to keep in mind:

  • ⚠️ Safari has special behavior: maintains browsing context for same-domain links
  • ⚠️ Third-party browsers (Chrome, Firefox, etc.) may not fully support them when configured as default

Useful resources

  • đź“ą Official Apple video: What’s New in Universal Links (WWDC 2020) - Complete session where Apple explains Universal Links
  • 🔍 Well-Known.dev: Tool to search and verify .well-known/ files on websites, including apple-app-site-association. Lets you see the associated domains of any page and verify your configuration is correct
  • đź“š Official documentation: Supporting Universal Links - Complete Apple documentation

In the next article I’ll explain how to test them in test environments, which is where most problems usually appear.

See you around 🫶