# AASA validator for iOS Universal Links

> Free apple-app-site-association (AASA) validator: test iOS Universal Links for any domain. Checks redirects, content type, size, app IDs, components and paths, with a fix for each problem. Shareable results.

Source: https://straitlink.in/tools/aasa-validator/
Markdown: https://straitlink.in/tools/aasa-validator.md

## AASA validator

Validate the apple-app-site-association file that lets iPhone links open your app: reachability, redirects, size, app IDs, components and paths, each problem with a fix. No account needed.

## How Universal Links get verified

Your app declares `applinks:your-domain` in its Associated Domains entitlement. When the app is installed, iOS asks Apple's CDN for that domain's `apple-app-site-association` file, which the CDN fetched from `https://your-domain/.well-known/apple-app-site-association`. If the file names your app ID (Team ID plus bundle ID) and a component matches the tapped URL, iOS opens the app instead of Safari.

Apple fetches the file without following redirects and ignores files over 128 KB. A signed file, a gzip body without the right header, or JSON with a trailing comma all make the whole domain fall back to Safari.

## Check Apple's copy too

This validator reads the file from your server, which is what Apple's CDN copies. To see what phones get right now, ask the CDN directly:

```
curl  -i  https://app-site-association.cdn-apple.com/a/v1/example.com
```

During development you can skip the CDN by adding `?mode=developer` to the entitlement (`applinks:example.com?mode=developer`) and turning on Associated Domains Development in the iPhone's Developer settings. If your links run on a Strait link domain, Strait serves this file from your app settings; iPhone links on Strait are live, tested on a real iPhone. To write a file from scratch, use the [AASA generator](https://straitlink.in/tools/aasa-generator/). To see which rule decides one particular link, paste it into the [deep link tester](https://straitlink.in/tools/deep-link-tester/).

## Every rule this checker reports

Each finding in a result links here. The id in grey (for example `ios.redirect`) is what the copied report shows. Rules found only at the old root location keep the same id. Checking Android links too? See the [assetlinks.json checker](https://straitlink.in/tools/assetlinks-checker/).

### The file could not be fetched Broken

`ios.fetch`

The checker could not download the file: DNS, TLS, a timeout or a private address. Apple's CDN would fail in the same way.

**Fix:** Make the URL load over https with a valid certificate, from the public internet, without a login or a bot challenge.

```
curl  -sv  https://example.com/.well-known/apple-app-site-association  -o  /dev/null
```

### The file is behind a redirect Broken

`ios.redirect`

Apple requires the file to be served directly with a 200. A redirect (apex to www, http to https inside the path, a trailing slash) makes the domain unverified.

**Fix:** Serve the file at exactly this URL on every host your links use.

```
# nginx: serve the file directly, as JSON, with no redirect
location = /.well-known/apple-app-site-association {
  default_type application/json;
  try_files $uri =404;
}
```

### The server did not answer 200 Broken

`ios.status`

A 404 means no file at /.well-known/apple-app-site-association. A 403 is often a CDN bot rule blocking Apple's fetcher.

**Fix:** Publish the file (no .json extension) and allow anonymous requests to it.

```
curl  -i  https://example.com/.well-known/apple-app-site-association
```

### A Strait link domain with no iPhone app yet Broken

`ios.not_set_up`

Strait serves this file for you on your link domain, but only once Dashboard → Apps & stores has your iPhone app. Until then the domain answers 404 "not configured".

**Fix:** Fill in Dashboard → Apps & stores (Team ID and bundle ID), wait a minute, then check again. Already done? Make sure the domain is your link domain from Dashboard → Setup → Your keys.

```
curl  -i  https:// < your-handl e > .strait.link/.well-known/apple-app-site-association
```

### Content-Type is not application/json Degraded

`ios.content_type`

The file has no extension, so many servers send application/octet-stream or text/plain. Apple expects application/json.

**Fix:** Set the Content-Type for this exact path.

```
# nginx: serve the file directly, as JSON, with no redirect
location = /.well-known/apple-app-site-association {
  default_type application/json;
  try_files $uri =404;
}
```

### The file is larger than 128 KB Broken

`ios.size`

Apple ignores association files over 128 KB uncompressed. Large files usually list every path one by one.

**Fix:** Replace long path lists with wildcards or components rules.

```
"components" : [{  "/" :  "/products/*"  }]
```

### The file is signed (CMS/PKCS#7) Broken

`ios.signed`

Signed association files were only needed before iOS 9. Current iOS expects plain, unsigned JSON.

**Fix:** Publish the plain JSON file instead.

```
{   "applinks" :  {     "details" :  [       {         "appIDs" :  [ "ABCDE12345.com.example.shop" ] ,         "components" :  [{  "/" :  "/products/*"  } ,  {  "/" :  "/admin/*" ,  "exclude" :  true  }]       }     ]   } }
```

### Gzip data without a Content-Encoding header Broken

`ios.gzip`

The body is gzip-compressed but the server did not say so, so the file cannot be read as JSON.

**Fix:** Serve the file uncompressed, or send Content-Encoding: gzip with it.

### Not valid JSON Broken

`ios.json`

The body could not be parsed: a trailing comma, a comment, or an HTML page in place of the file. iOS ignores it.

**Fix:** Validate the file and fix the syntax error. Do not add .json to the URL.

```
python3  -m  json.tool  apple-app-site-association
```

### The file starts with a byte-order mark Degraded

`ios.bom`

An invisible UTF-8 BOM comes before the JSON. Some parsers reject it.

**Fix:** Save the file as UTF-8 without BOM.

```
sed  -i  '1s/^\xEF\xBB\xBF//'  apple-app-site-association
```

### The file must be a JSON object Broken

`ios.shape`

The file is an object with keys such as applinks and webcredentials, not an array.

**Fix:** Use the object format.

```
{   "applinks" :  {     "details" :  [       {         "appIDs" :  [ "ABCDE12345.com.example.shop" ] ,         "components" :  [{  "/" :  "/products/*"  } ,  {  "/" :  "/admin/*" ,  "exclude" :  true  }]       }     ]   } }
```

### No "applinks" section Broken

`ios.applinks`

Without applinks, no app can open links on this domain as Universal Links (webcredentials alone only covers password autofill).

**Fix:** Add an applinks section.

```
{   "applinks" :  {     "details" :  [       {         "appIDs" :  [ "ABCDE12345.com.example.shop" ] ,         "components" :  [{  "/" :  "/products/*"  } ,  {  "/" :  "/admin/*" ,  "exclude" :  true  }]       }     ]   } }
```

### "applinks.apps" should be an empty list Degraded

`ios.apps_key`

This legacy key must be [] when present. iOS 13 and later ignore it.

**Fix:** Set it to [] or remove it.

```
"apps" : []
```

### "applinks.details" is missing or empty Broken

`ios.details`

details lists which apps may open which paths. Without it, no app opens links.

**Fix:** Add at least one entry with appIDs and components.

```
{   "applinks" :  {     "details" :  [       {         "appIDs" :  [ "ABCDE12345.com.example.shop" ] ,         "components" :  [{  "/" :  "/products/*"  } ,  {  "/" :  "/admin/*" ,  "exclude" :  true  }]       }     ]   } }
```

### A details entry is not an object Broken

`ios.detail`

Each entry in details is an object with appIDs and components (or the older appID and paths).

**Fix:** Use one object per group of apps.

```
{   "applinks" :  {     "details" :  [       {         "appIDs" :  [ "ABCDE12345.com.example.shop" ] ,         "components" :  [{  "/" :  "/products/*"  } ,  {  "/" :  "/admin/*" ,  "exclude" :  true  }]       }     ]   } }
```

### A details entry names no app Broken

`ios.detail_ids`

Each entry needs appIDs (a list, iOS 13+) or appID (a string, the older format).

**Fix:** Add appIDs with your Team ID and bundle ID.

```
"appIDs" : [ "ABCDE12345.com.example.shop" ]
```

### Invalid app ID Broken

`ios.appid`

An app ID is your 10-character Team ID, a dot, then the bundle ID (ABCDE12345.com.example.shop). The Team ID part is uppercase letters and digits.

**Fix:** Copy the Team ID from developer.apple.com → Membership and the bundle ID from Xcode → Signing & Capabilities.

```
"appIDs" : [ "ABCDE12345.com.example.shop" ]
```

### An app ID looks like a placeholder Degraded

`ios.placeholder`

The app ID looks like an example value (TEAMID, ABCDE12345, com.example), so no real app will match it.

**Fix:** Replace it with your real Team ID and bundle ID.

### An entry has no paths or components Broken

`ios.detail_rules`

Without components (iOS 13+) or paths (older), the entry matches no URL.

**Fix:** Add components. { "/": "*" } matches every path.

```
"components" : [{  "/" :  "*"  }]
```

### "paths" is malformed or never matches Broken

`ios.paths`

paths is a list of strings such as "/products/*" or "NOT /admin/*". A URL path always starts with /, so a pattern (after an optional "NOT ") that starts with anything other than /, * or ? can never match.

**Fix:** Fix the patterns, or move to components, which iOS 13 and later prefer.

```
"paths" : [ "/products/*" ,  "NOT /admin/*" ]
```

### "components" must be a list Broken

`ios.components`

components is an array of objects, one per rule.

**Fix:** Make it an array.

```
"components" : [{  "/" :  "/products/*"  }]
```

### A component is malformed or has unknown keys Degraded

`ios.component`

Each component is an object with keys "/", "?", "#", "exclude", "comment", "caseSensitive" or "percentEncoded". iOS ignores other keys, so the rule may match more or less than you expect.

**Fix:** Use only the documented keys.

```
{  "/" :  "/products/*" ,  "?" :  {  "ref" :  "*"  } ,  "exclude" :  false  }
```

### A "/" pattern looks wrong Degraded

`ios.component_path`

The "/" value should be a path pattern starting with / or *.

**Fix:** Use a pattern like /products/*.

```
{  "/" :  "/products/*"  }
```

### "?" must be a string or an object Broken

`ios.component_query`

Query matching takes a pattern string, or an object of parameter name → pattern.

**Fix:** Use an object for named parameters.

```
{  "/" :  "/s/*" ,  "?" :  {  "ref" :  "*"  } }
```

### "#" must be a string Broken

`ios.component_fragment`

Fragment matching takes a pattern string.

**Fix:** Use a string pattern.

```
{  "#" :  "section-*"  }
```

### "exclude" must be true or false Broken

`ios.component_exclude`

exclude is a JSON boolean. "true" in quotes is a string and is not read as an exclusion.

**Fix:** Remove the quotes.

```
{  "/" :  "/admin/*" ,  "exclude" :  true  }
```

### "webcredentials" is malformed Degraded

`ios.webcredentials`

webcredentials (optional, for password autofill) must be { "apps": ["TEAMID.bundle.id"] }.

**Fix:** Fix the format or remove the section.

```
"webcredentials" : {  "apps" :  [ "ABCDE12345.com.example.shop" ] }
```

### The file is only at the old root location Degraded

`ios.legacy_only`

The file exists at /apple-app-site-association but not at /.well-known/apple-app-site-association. Apple looks in /.well-known/ first; the root location is a legacy fallback.

**Fix:** Serve the same file at the /.well-known/ path.

```
# nginx: serve the file directly, as JSON, with no redirect
location = /.well-known/apple-app-site-association {
  default_type application/json;
  try_files $uri =404;
}
```

### Apps allowed to open links OK

`ios.apps`

The app IDs this domain lets open its links as Universal Links.

### apple-app-site-association looks correct OK

`ios.valid`

Served over https with a 200, no redirect, valid JSON and well-formed rules. iPhones read the file through Apple's CDN, which caches it, so a fix can take a while to reach phones. Apple's CDN copy is at app-site-association.cdn-apple.com/a/v1/<your domain>.

```
curl  -i  https://app-site-association.cdn-apple.com/a/v1/example.com
```

## Questions

I fixed the file. Why do iPhones still open Safari?

iPhones do not read your server directly. They read a copy from Apple's CDN, which refreshes on its own schedule, and a phone re-checks when the app is installed or updated. Check what Apple's CDN currently holds at app-site-association.cdn-apple.com/a/v1/your-domain, then reinstall the app to test.

Do I need the .json extension?

No. The file is called apple-app-site-association with no extension, served at /.well-known/apple-app-site-association with Content-Type application/json.

components or paths?

components is the format for iOS 13 and later and supports query and fragment matching and exclusions. paths is the older format. You can keep both in the same entry while you still support older iOS versions.

Why does a link typed into Safari's address bar not open my app?

Universal Links open the app when someone taps a link in another app or page. Typing or pasting the address into Safari, or tapping a link to the same domain you are already on, keeps you in Safari by design.

Is this checker's result the same as what an iPhone sees?

It checks the file your domain serves. Apple's CDN may still hold an older copy, and the app needs the Associated Domains entitlement (applinks:your-domain) for the file to matter. The rule notes below cover both.

## One link for iPhone, Android and the web

Strait hosts the association files on your link domain, routes each tap to the app, the store or the web, and shows you what happened.

[Start free](https://app.straitlink.in/?signup=1)

## More free tools

[### Is my app link broken? Paste a page.link, Branch, OneLink, Adjust or any deep link and see what Android, iPhone and desktop get: the app, the store, a web page, or nothing.](https://straitlink.in/tools/link-checker/)
[### Will it open my app? Pick where the link is tapped (WhatsApp, Instagram, Gmail, Chrome, Safari) and see the decision Strait makes for that tap, step by step.](https://straitlink.in/tools/will-it-open/)
[### Test my link on your phone Send a link to your own phone by QR, WhatsApp, Telegram, email or SMS, then tick off what each in-app browser shows against what it should.](https://straitlink.in/tools/test-my-link/)
