# Universal Links are properly configured for iOS

- **Pattern:** `ab-001859` (`mobile-navigation-linking.deep-linking.universal-links-ios`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001859
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001859)

## Why it matters

Without a valid `apple-app-site-association` file, iOS treats your HTTPS links as ordinary web URLs and opens them in Safari instead of launching your app. Users who tap a password-reset link, a share URL, or a post-purchase confirmation get dropped into a browser session with no app context — they abandon, or worse, complete a flow in an unsupported UI path. Apple's Universal Links spec (apple-universal-links) requires server-side verification; if `/.well-known/apple-app-site-association` is missing or misconfigured, the OS silently falls back to Safari with no error shown to the user or the developer.

## Severity rationale

High because misconfigured Universal Links silently break every HTTPS deep link on iOS, routing users to a browser instead of the app and degrading retention, re-engagement, and post-purchase flows.

## Remediation

Place the `apple-app-site-association` file at `ios/apple-app-site-association` and ensure it is also served at `https://<your-domain>/.well-known/apple-app-site-association` with `Content-Type: application/json` and no redirect.

```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.yourcompany.appname",
        "paths": ["/*"]
      }
    ]
  }
}
```

For Expo-managed builds, add the domain to `app.json` instead:

```json
{
  "ios": {
    "associatedDomains": ["applinks:myapp.com"]
  }
}
```

Replace `TEAM_ID` with your Apple Developer Team ID. Verify the file is reachable and returns HTTP 200 before submitting to the App Store.

## Detection

- **ID:** `universal-links-ios`
- **Severity:** `high`
- **What to look for:** Check for `apple-app-site-association` file. This file should exist in your `ios/` directory or be served at `https://<your-domain>/.well-known/apple-app-site-association` on your backend. The file should specify your app's team ID and associated domains. For Expo-managed projects, check `app.json` for `ios.associatedDomains` config.
- **Pass criteria:** Count all associated domain entries in app.json or apple-app-site-association. Either an `apple-app-site-association` file exists in the iOS build, or `app.json` contains at least 1 `ios.associatedDomains` entry pointing to your domain. The file/config includes your app's team ID or bundle identifier. Before evaluating, extract and quote the `ios.associatedDomains` array value if present.
- **Fail criteria:** No `apple-app-site-association` file or config found. iOS universal links are not configured.
- **Skip (N/A) when:** The app has no iOS support (no `ios` field in app.json), or universal links are not required (custom scheme-only deep links are acceptable).
- **Detail on fail:** `"No apple-app-site-association file found in ios/ directory"` or `"app.json has no ios.associatedDomains configuration"`
- **Remediation:** Configure Universal Links for iOS. In your `ios/` directory, create `apple-app-site-association` (no file extension):

  ```json
  {
    "applinks": {
      "apps": [],
      "details": [
        {
          "appID": "TEAM_ID.com.yourcompany.appname",
          "paths": ["/*"]
        }
      ]
    },
    "webcredentials": {
      "apps": ["TEAM_ID.com.yourcompany.appname"]
    }
  }
  ```

  Replace `TEAM_ID` with your Apple Developer Team ID and adjust the bundle ID. Alternatively, in `app.json` for Expo:

  ```json
  {
    "ios": {
      "associatedDomains": ["applinks:myapp.com", "webcredentials:myapp.com"]
    }
  }
  ```

## External references

- external apple-universal-links — https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app

Taxons: user-experience, operational-readiness

HTML version: https://auditbuffet.com/patterns/ab-001859