Documentation

Universal Links

Configure Universal Links on iOS so a tap on your website link lands the user in your app instead of Safari. AASA file generated, hosted, and served at the right path.

Universal Links let users tap a link to your website and be taken directly to your app, rather than Safari. This requires an apple-app-site-association (AASA) file hosted at your domain.

Configuration

In the Dashboard, go to the Associated Domains section and configure Universal Links:

  1. Add App IDs — Enter your App ID in the format TEAMID.com.example.app. Your Team ID is a 10-character alphanumeric string found in your Apple Developer account.
  2. Add URL Patterns — Specify which URL paths should open in your app (e.g., /products/*). You can mark patterns as excluded to keep certain URLs in Safari (e.g., /admin/*).

After deploying, your AASA file is served at both /.well-known/apple-app-site-association (the path Apple’s CDN fetches) and /apple-app-site-association (the legacy root path that some validators still probe). OrbitKit serves it with Content-Type: application/json, no .json extension, and no redirects — the three things devs most often get wrong.

Custom domain required Universal Links only work on domains you own. You must configure a custom domain to use this feature. Apple looks for the AASA file at the domain root, so the slug-based sites.orbitkit.io/your-slug URL alone is not sufficient.

Xcode setup

In your Xcode project:

  1. Select your app target and go to Signing & Capabilities.
  2. Click + Capability and add Associated Domains.
  3. Add applinks:your-domain.com.
// In your AppDelegate or SceneDelegate
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }
    // Handle the URL in your app
    return handleUniversalLink(url)
}

Apple reference: Supporting Universal Links in Your App · TN3155: Debugging universal links

Debugging tips

Apple’s CDN caches your AASA file

Starting with iOS 14, devices don’t fetch your AASA file directly — Apple’s CDN does, then devices pull from there. The CDN refreshes roughly every 24–48 hours, so a freshly-deployed change can take a while to show up on real devices. To inspect what the CDN currently has, visit:

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

Bypass the CDN during development with ?mode=developer

In Xcode, change your Associated Domains entitlement from applinks:your-domain.com to applinks:your-domain.com?mode=developer. This tells iOS to fetch the AASA file directly from your origin instead of Apple’s CDN, so you see changes immediately. Remove this before submitting to the App Store — it’s a development-only flag.

Force iOS to re-fetch the AASA file

iOS doesn’t re-scrape the AASA file on app updates from the App Store (that’s a known limitation). To force a refresh during development, delete and reinstall the app. Long-press a link in the Notes app to verify whether iOS picked up your latest config.

File size limit

Apple’s swcd daemon refuses AASA files larger than 128 KB. OrbitKit validates this when you save your AASA config — if you’re hitting it, you have too many path patterns or App IDs and should consolidate.