iOS多环境（Dev/QA/Prod）通用链接配置及AASA文件实现问询

Great question! This is a super common scenario for teams building multi-environment iOS apps, and Universal Links can absolutely handle it—you just need to structure your Apple App Site Association (AASA) file and app entitlements strategically to ensure each URL opens the correct environment’s app, even if all three are installed on the same device.

Core Approach #

The key is to use URL path segmentation to map specific paths on www.mywebsite.com to each environment’s app. This way, iOS can precisely match which app should handle a given link, eliminating ambiguity even when all three apps are installed.

Step 1: Use Unique Bundle IDs for Each Environment #

First, make sure each environment’s app has a distinct Bundle ID (this is non-negotiable, since each app needs a unique identity for Universal Links):

• Prod: com.yourcompany.yourapp.prod
• QA: com.yourcompany.yourapp.qa
• Dev: com.yourcompany.yourapp.dev

Step 2: Configure Associated Domains Entitlements #

For each app, enable the Associated Domains capability in Xcode and add the domain applinks:www.mywebsite.com. This tells iOS that the app is registered to handle links from your website.

Make sure this capability is also enabled for each app in the Apple Developer Portal (under App IDs > Capabilities).

Step 3: Structure Your AASA File #

This is the critical piece. Your AASA file (hosted at https://www.mywebsite.com/.well-known/apple-app-site-association) will map specific URL paths to each app’s Bundle ID (prefixed with your Apple Team ID).

Here’s a working example:

{
  "applinks": {
    "details": [
      {
        "appIDs": ["YOUR_TEAM_ID.com.yourcompany.yourapp.prod"],
        "paths": ["/prod/*", "/"] // Root path defaults to Prod
      },
      {
        "appIDs": ["YOUR_TEAM_ID.com.yourcompany.yourapp.qa"],
        "paths": ["/qa/*"]
      },
      {
        "appIDs": ["YOUR_TEAM_ID.com.yourcompany.yourapp.dev"],
        "paths": ["/dev/*"]
      }
    ]
  }
}

How This Works:

• Links like https://www.mywebsite.com/prod/checkout or the root https://www.mywebsite.com will only match the Prod app’s path rules, so iOS opens the Prod app directly.
• Links like https://www.mywebsite.com/qa/test-login will only match the QA app’s rules, opening QA.
• Links like https://www.mywebsite.com/dev/debug will only match the Dev app’s rules, opening Dev.

Step 4: Handle Simultaneous Installations #

Since each URL path is explicitly mapped to only one app, iOS won’t show a "Open in..." prompt when all three apps are installed. It will immediately open the app that matches the path in the link.

Critical Notes #

• Replace YOUR_TEAM_ID: Find your Team ID in the Apple Developer Portal (under Membership Details).
• Path Matching Rules: Use * as a wildcard for subpaths, NOT to exclude paths (e.g., "NOT /dev/*"), and exact paths for specific URLs. Apple’s path matching is case-insensitive and follows specific precedence rules—stick to explicit paths/wildcards for clarity.
• AASA Deployment: Ensure the file is served over HTTPS, has no redirects, and uses the application/json MIME type. iOS will not fetch the file if these conditions aren’t met.
• Testing: After deploying the AASA file, install each app on a test device and test links from Notes, Safari, or other apps. You can check Xcode’s console logs for errors related to Universal Link validation.

内容的提问来源于stack exchange，提问作者Matias Jurfest