Skip to content
Tolinku Docs

What are Universal Links?

Universal Links are Apple’s mechanism for opening your app when a user taps an HTTPS link that belongs to your domain. They replaced the older custom URL scheme approach and provide a more reliable, secure deep linking experience.

Section titled “How Universal Links work”
  1. You host an Apple App Site Association (AASA) file on your web server at /.well-known/apple-app-site-association.
  2. You add the Associated Domains entitlement to your app with your domain.
  3. When a user installs your app, iOS downloads the AASA file from your domain and registers the association.
  4. When a user taps a link to your domain, iOS checks if the path matches the AASA file. If it does, the app opens. If not, Safari opens.

The AASA file

Section titled “The AASA file”

The AASA file is a JSON document that tells iOS which paths on your domain should open in your app:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "A1B2C3D4E5.com.example.myapp",
        "paths": ["/product/*", "/invite", "/ref/*"]
      }
    ]
  }
}
  • appID is your Team ID and Bundle ID, joined by a dot.
  • paths lists the URL paths that should open in the app. * is a wildcard.
  • NOT /path excludes a path from app opening.

The file must be served at https://yourdomain.com/.well-known/apple-app-site-association with Content-Type: application/json and no redirects.

Section titled “Why Universal Links are better than URL schemes”
FeatureUniversal LinksCustom URL schemes
ProtocolHTTPS (standard)Custom (e.g. myapp://)
FallbackOpens in Safari if app not installedShows an error if app not installed
SecurityVerified via AASA fileNo verification, any app can claim a scheme
User experienceSeamless, no promptMay show a “Open in app?” dialog

Key behaviors

Section titled “Key behaviors”
  • First install only. iOS fetches the AASA file when the app is installed (or updated). Changes to the AASA file take effect for new installs or app updates, not immediately for existing users.
  • Apple CDN. On iOS 14+, Apple fetches AASA files through its own CDN, which may cache them for up to 24 hours.
  • Long-press override. Users can long-press a Universal Link and choose “Open in Safari” instead. Once they do this, iOS remembers the preference. They can reverse it by long-pressing again and choosing “Open in App.”
  • Same-domain restriction. Universal Links only work when the user navigates from a different domain. Links within the same domain (e.g. tapping a link on your own website) open in Safari, not the app.
Section titled “How Tolinku handles Universal Links”

Tolinku automatically generates and serves the AASA file for your Appspace’s domain. You configure your Bundle ID and Team ID in Appspace Settings, enable Universal Links on each route, and Tolinku builds the correct paths array.

See Universal Links (iOS) for the setup guide.