Universal links: the setup that fails without an error

Checking the files from outside

Do this from a machine that is not yours, because a cached or local answer is not the answer:

# iOS: must be JSON, 200, no redirect
curl -sIL https://example.com/.well-known/apple-app-site-association | head -20
curl -s https://example.com/.well-known/apple-app-site-association | head -40

# Android
curl -s https://example.com/.well-known/assetlinks.json | head -40

# the things to confirm in the headers
# - HTTP/2 200, not 301 or 302
# - content-type: application/json
# - no authentication, no geo-blocking, no bot protection challenge

Bot protection is the modern version of this problem. A challenge page served to a non-browser client returns something that is not your JSON, and the platform sees exactly what curl sees.

The Expo specifics

// app.json
"ios": { "associatedDomains": ["applinks:example.com"] },
"android": {
  "intentFilters": [{
    "action": "VIEW",
    "autoVerify": true,
    "data": [{ "scheme": "https", "host": "example.com" }],
    "category": ["BROWSABLE", "DEFAULT"]
  }]
}

Then verify it survived generation, because a config that is correct in app.json and absent from the build is the second most common cause after the file:

npx expo prebuild --clean
grep -A3 'associated-domains' ios/*/*.entitlements
grep -A6 'intent-filter' android/app/src/main/AndroidManifest.xml

Editing the generated ios/ or android/ directly works locally and disappears at the next build. The EAS submission checklist. · Auditing what your config plugins added.

Testing it properly

1. Fix everything. Confirm the files with curl from outside.
2. Delete the app from the test device.
3. Reinstall. Verification happens around install.
4. Open the link from Notes or Messages, not from a browser
   address bar, which does not always behave the same way.
5. Test a path that should open the app and one that should not.
6. Test with the app force-quit, and with it backgrounded.

Step two is the one people skip, and it is the reason this gets debugged for a day.

The Android fingerprint

assetlinks.json carries the SHA-256 fingerprint of the signing certificate. With Play App Signing, Google re-signs your bundle, so the fingerprint that matters is the one from the Play Console's app signing page, not the one from your upload key.

Publishing the upload key's fingerprint is a silent failure that looks exactly like everything else being wrong. Check the Console.

Why this matters beyond convenience

A broken link is a broken feature, and if onboarding, a password reset, an invite flow or your review notes depend on a link opening the app, a reviewer experiences an app that does not work. That is reported as Guideline 2.1 completeness rather than as a linking problem, which is why the guideline number does not find you the answer.

And it is the kind of thing that works in development and fails in production, because the domain, the certificate and the hosting are all different there. Test against the production domain with the production build. Shipping your first update.

shipcheck reports whether the domains declared in your app config match the association files your site actually serves, and flags a signing fingerprint mismatch. What it checks. · When a dependency blocks your release.

Questions and answers