Universal Links异常：Safari未显示应用打开横幅问题排查

Hey there! Let's work through why that Universal Links banner isn't popping up for your app. I've debugged this exact issue countless times, so here are the critical checks to run through step by step:

1. Fix Your Associated Domains Entitlement Format #

This is one of the most common mistakes! You mentioned adding applinks:v100.xxxxxx.com/reset_password* to your Entitlements, but you shouldn't include paths in the associated domain entry. Path matching is handled entirely in the apple-app-site-association file, not the entitlement.

Update your Entitlements to use this format instead:

applinks:v100.xxxxxx.com

2. Validate Your apple-app-site-association File #

First, make sure the file is deployed to the correct domain—your test link uses v100.xxxxxxx.com, so Apple will look for the file at either:

• https://v100.xxxxxxx.com/apple-app-site-association
• https://v100.xxxxxxx.com/.well-known/apple-app-site-association

If you only deployed it to www.xxxxx.com, that's the problem. Move or copy the file to the v100.xxxxxxx.com domain's root or .well-known directory.

Next, confirm the file structure is 100% correct (no .json suffix, valid JSON):

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "YOUR_TEAM_ID.YOUR_BUNDLE_ID",
        "paths": [ "/reset_password*" ]
      }
    ]
  }
}

• Replace YOUR_TEAM_ID with your Apple Developer Team ID (found in your Developer Account)
• Replace YOUR_BUNDLE_ID with your app's exact Bundle Identifier
• Double-check the paths array: does /reset_password* actually cover your test URL (https://v100.xxxxxxx.com/reset...)? If your test path starts with /reset instead of /reset_password, adjust the rule to /reset* to match.

3. Verify File Accessibility & Headers #

Even if you can access the file, ensure these requirements are met:

• The file is served over HTTPS with a valid, trusted SSL certificate (no self-signed certs)
• No redirects—requests to the file URL must return the content directly
• The Content-Type response header should be application/json (some servers use text/plain which works, but application/json is more reliable)

4. Check Device & Safari Settings #

• Make sure your app is installed on the test device (use Ad Hoc, TestFlight, or App Store builds—Xcode debug builds work too, but ensure Entitlements are applied)
• Enable "Link to Apps" in Safari: Go to Settings > Safari > General > Link to Apps and toggle it on
• If you previously tapped "Don't Open" for your app, reset this preference by clearing Safari's website data: Settings > Safari > Clear History and Website Data

5. Reinstall the App & Restart Safari #

Entitlement changes sometimes don't take effect until you reinstall the app. Delete the app from your device, reinstall it (via Xcode, TestFlight, etc.), then fully close and restart Safari before testing again.

6. Use Apple's Validation Tool #

Apple provides an official tool to validate your Universal Links setup. It will flag issues like incorrect file formatting, mismatched app IDs, or domain access problems. Run this tool against your v100.xxxxxxx.com domain to catch any hidden errors.

内容的提问来源于stack exchange，提问作者Satheeshkumar Naidu