Skip to content
Tolinku
Sign In Start Free
Tolinku
Sign In Start Free
iOS Development · · 6 min read

Universal Links Across iOS Versions: A Compatibility Guide

By Tolinku Staff
|
Tolinku universal links dashboard screenshot for ios blog posts

Universal Links have been available since iOS 9, but their behavior has changed with nearly every major iOS release. AASA file format changes, new validation rules, CDN caching behavior, and Safari interaction quirks all vary by version. If you support a range of iOS versions, you need to know what works where.

This article documents the significant Universal Links changes across iOS versions so you can test and configure accordingly.

For Universal Links fundamentals, see universal links: everything you need to know. For iOS 17 specifically, see Universal Links changes in iOS 17.

iOS 9: The Beginning

iOS 9 (2015) introduced Universal Links. The initial implementation established the core concepts that remain today:

  • Apps declare supported domains via the Associated Domains entitlement.
  • The domain hosts an AASA file at /.well-known/apple-app-site-association or /apple-app-site-association.
  • iOS downloads the AASA file when the app is installed and checks it periodically.
  • Tapping a matching URL opens the app instead of Safari.

The original AASA format used appID (singular) and a paths array:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.example.app",
        "paths": ["/product/*", "/category/*"]
      }
    ]
  }
}

The apps key was required to be an empty array. Apple's documentation at the time: Support Universal Links.

Key Behaviors in iOS 9

  • AASA file downloaded directly from your domain (no Apple CDN).
  • The file had to be served with Content-Type: application/json.
  • No support for query parameter or fragment matching.
  • WKWebView did not dispatch Universal Links to the system.

iOS 10-11: Stability

iOS 10 and 11 did not introduce major changes to Universal Links behavior. The core functionality remained the same. Notable points:

  • iOS 11 introduced SFAuthenticationSession (later replaced by ASWebAuthenticationSession) for OAuth flows, reducing the need to use SFSafariViewController for authentication. See SFSafariViewController and deep links.
  • Intelligent Tracking Prevention (ITP) in iOS 11 Safari affected third-party cookie behavior, which impacted some deep linking attribution flows that relied on cross-domain cookies.

iOS 13: The Modern AASA Format

iOS 13 was the biggest change since the introduction of Universal Links. Apple introduced the modern AASA format with the components array:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAMID.com.example.app"],
        "components": [
          { "/": "/product/*", "comment": "Product pages" },
          { "/": "/admin/*", "exclude": true, "comment": "Exclude admin" }
        ]
      }
    ]
  }
}

What Changed

  • appIDs (plural) replaced appID (singular). You can now list multiple app IDs in a single entry.
  • components array replaced paths. Each component is an object with a / key for the path pattern.
  • Exclusions use "exclude": true instead of the NOT prefix.
  • Query parameter matching via the ? key in components.
  • Fragment matching via the # key in components.
  • comment field for documentation within the AASA file.
  • Scene-based lifecycle. Apps using UIWindowSceneDelegate receive Universal Links via scene(_:continue:) instead of the app delegate method. Both still work.

Backward Compatibility

The legacy format is still supported on iOS 13+. If you need to support iOS 9-12, you can include both formats in the same AASA file. iOS will use the format it understands:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.example.app",
        "paths": ["/product/*"]
      },
      {
        "appIDs": ["TEAMID.com.example.app"],
        "components": [
          { "/": "/product/*" }
        ]
      }
    ]
  }
}

For details on the modern format, see AASA wildcards and path matching.

iOS 14: Apple CDN and App Clips

iOS 14 introduced two significant changes:

Apple CDN for AASA Files

Starting with iOS 14, Apple's CDN fetches and caches AASA files from your domain. Devices no longer download the AASA file directly from your server. Instead:

  1. Your server hosts the AASA file.
  2. Apple's CDN (app-site-association.cdn-apple.com) periodically fetches it.
  3. iOS devices download the cached version from Apple's CDN.

This improved reliability (your server being down does not break Universal Links for already-installed apps) but introduced caching delays. Changes to your AASA file may take hours to days to propagate through Apple's CDN.

You can check Apple's cached version:

https://app-site-association.cdn-apple.com/a/v1/yourdomain.com

For CDN caching details, see CDN and AASA caching.

App Clips

iOS 14 also introduced App Clips, which share the AASA infrastructure. The AASA file gained an appclips section alongside applinks. See Universal Links vs App Clips for a comparison.

iOS 15: Managed Associated Domains

iOS 15 added support for managed Associated Domains via MDM (Mobile Device Management). This is relevant for enterprise apps:

  • MDM profiles can configure Associated Domains for managed apps.
  • This allows enterprise apps distributed outside the App Store to use Universal Links.
  • The managed key in the AASA file's components controls which paths are available to managed apps.

Apple's documentation: Supporting Associated Domains.

iOS 16: Developer Mode and Alternate Modes

iOS 16 introduced:

  • Developer Mode requirement. On iOS 16+, testing Universal Links on a physical device requires Developer Mode to be enabled in Settings > Privacy & Security.
  • Alternate mode for Associated Domains. The ?mode=developer flag for the Associated Domains entitlement allows bypassing Apple's CDN validation during development:
applinks:yourdomain.com?mode=developer

In developer mode, iOS fetches the AASA file directly from your server instead of Apple's CDN, making development and testing faster.

For testing approaches, see testing Universal Links.

iOS 17: Stricter Validation

iOS 17 brought the most significant tightening of Universal Links validation since iOS 14. Key changes:

  • Stricter AASA validation. iOS 17 is less forgiving of AASA formatting issues that older versions tolerated.
  • HTTPS enforcement. The AASA file must be served over HTTPS with a valid certificate. Self-signed certificates no longer work in production.
  • Content-Type requirements. The AASA file must be served with Content-Type: application/json. Some servers that previously served it with application/octet-stream saw breakage.
  • CDN refresh behavior changes. The frequency and timing of Apple CDN refreshes changed, requiring developers to be more deliberate about AASA updates.

For detailed iOS 17 changes, see Universal Links changes in iOS 17.

iOS 18: Continued Refinement

iOS 18 continued the trend of incremental improvements:

  • Improved CDN update propagation. Apple reduced the delay between AASA file changes and CDN cache updates.
  • Better error reporting. Console logs for Universal Link failures became more descriptive, making debugging easier.
  • SwiftUI improvements. The onOpenURL modifier in SwiftUI received better integration with the scene lifecycle.

For SwiftUI-specific handling, see Universal Links with SwiftUI.

Version Compatibility Matrix

Feature iOS 9-12 iOS 13 iOS 14 iOS 15 iOS 16 iOS 17+
Legacy AASA format Yes Yes Yes Yes Yes Yes
Modern AASA format No Yes Yes Yes Yes Yes
Query/fragment matching No Yes Yes Yes Yes Yes
Apple CDN caching No No Yes Yes Yes Yes
Developer mode bypass No No No No Yes Yes
App Clips integration No No Yes Yes Yes Yes
Managed domains (MDM) No No No Yes Yes Yes
Strict AASA validation No No No No No Yes

Practical Recommendations

If you support iOS 13+ (the majority of active devices), use the modern AASA format exclusively. The components array is more expressive and better documented.

If you still support iOS 12 or earlier, include both legacy and modern format entries in your AASA file. iOS will use the format it understands.

Always test on the oldest iOS version you support. AASA parsing differences between versions can cause Universal Links to work on iOS 17 but fail on iOS 14.

Use developer mode during development. The ?mode=developer flag (iOS 16+) bypasses CDN caching and makes iteration faster.

Monitor Apple's CDN. After updating your AASA file, check app-site-association.cdn-apple.com to verify the update propagated. See CDN and AASA caching.

Tolinku for Cross-Version Compatibility

Tolinku generates AASA files that are compatible across all supported iOS versions. The platform handles format differences, ensuring your deep links work whether the user is on iOS 14 or iOS 18. See the Universal Links developer guide for setup details, or the iOS troubleshooting guide if you encounter version-specific issues.

For the complete Universal Links guide, see universal links: everything you need to know. For deep linking standards across platforms, see deep linking standards in 2026.

app-development apple compatibility Deep Linking iOS mobile-development Swift testing troubleshooting Universal Links

Get deep linking tips in your inbox

One email per week. No spam.

In this article

Ready to add deep linking to your app?

Set up Universal Links, App Links, deferred deep linking, and analytics in minutes. Free to start.

Start Free View Documentation

Related articles