How to Update iOS App Deep Link Configuration: Complete AASA Guide

With the rapid development of mobile applications, providing seamless linking experiences has become a crucial aspect of enhancing user experience. For iOS developers, this means properly configuring the .well-known/apple-app-site-association (AASA) file to support deep linking functionality that opens apps directly. This article provides an in-depth exploration of AASA file configuration, updates, and troubleshooting.

What are Deep Links and Universal Links?

Deep Links are a technology that allows users to jump directly from web links to specific pages within mobile applications. In the iOS ecosystem, Apple provides the Universal Links mechanism to implement this functionality.

Advantages of Universal Links

Seamless Experience: Users tap a web link and go directly into the app without browser intermediation
High Security: Verifies domain ownership through HTTPS, preventing third-party apps from hijacking links
Fallback Mechanism: If the app isn’t installed, the link automatically opens the web version in Safari
Cross-Platform Consistency: The same URL works properly across iOS, Android, and Web

Role and Structure of AASA Files

The AASA file is a JSON-format configuration file that tells iOS devices which websites or web pages should open directly in your app. This is crucial for providing a smooth user experience, especially when users navigate from a website to content related to your app.

AASA File Structure Example

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.example.app",
        "paths": [
          "/articles/*",
          "/products/*",
          "NOT /api/*"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["TEAM_ID.com.example.app"]
  }
}

Key Field Descriptions

appID: Composed of Apple Developer Team ID and Bundle Identifier (format: TEAM_ID.BUNDLE_ID)
paths: Defines which URL paths should open in the app
- /articles/*: Matches all paths beginning with /articles/
- NOT /api/*: Excludes /api/ paths (keeps them in browser)
webcredentials: Supports Password AutoFill functionality (optional)

Steps to Deploy AASA Files

Step 1: Create AASA File

# Create file (no extension)
touch apple-app-site-association

# Edit file content (JSON format)
vi apple-app-site-association

Important Notes:

Filename must be apple-app-site-association (no extension)
Must be valid JSON format
Cannot include comments

Step 2: Deploy to Website Root Directory

The AASA file must be placed in the website’s .well-known directory and served via HTTPS:

https://yourdomain.com/.well-known/apple-app-site-association

Server Configuration Requirements:

Must use HTTPS (HTTP not supported)
Content-Type should be application/json or application/pkcs7-mime
File size limit of 128 KB
No redirects allowed (HTTP 301/302)

Step 3: Configure Associated Domains in Xcode

1. Open Xcode project
2. Select Target → Signing & Capabilities
3. Click "+ Capability" to add "Associated Domains"
4. Add domain: applinks:yourdomain.com

Updating AASA Files

After updating the AASA file, iOS devices automatically recognize these changes during their next update check. This process is automatic but may take some time, as iOS checks for updates on its own schedule (typically within 24 hours).

iOS Update Mechanism

App Installation: Checks AASA immediately when first installing the app
App Updates: Rechecks after updating the app from App Store
Periodic Checks: iOS periodically checks for AASA updates (approximately every 24 hours)
Device Restart: May trigger a recheck after restarting the device

Methods to Accelerate Updates

While there’s no official, direct method to force immediate updates across all devices, the following strategies can help accelerate the process:

Release App Update: Publish an app version that includes necessary changes to prompt user updates. This triggers iOS devices to recheck app-related configuration files, including the AASA file.
Provide User Guidance: Through app notifications or customer service, suggest users restart their devices or reinstall the app to help accelerate updates.
Use App Clips: If rapid update deployment is needed, consider using the App Clips mechanism.

Validating AASA Files

Using Apple’s Official Validation Tool

Apple provides an AASA validator to check file configuration:

https://search.developer.apple.com/appsearch-validation-tool/

Enter your domain and App ID, and the tool automatically checks:

Whether the AASA file is accessible (HTTPS)
Whether the JSON format is correct
Whether the appID matches
Whether the Content-Type is correct

Command Line Validation

# Check if file is accessible
curl -I https://yourdomain.com/.well-known/apple-app-site-association

# Download and check content
curl https://yourdomain.com/.well-known/apple-app-site-association | jq .

# Check Content-Type
curl -I https://yourdomain.com/.well-known/apple-app-site-association | grep -i content-type

Common Issues and Solutions

Issue 1: Universal Links Not Working

Possible Causes:

AASA file not accessible via HTTPS
Incorrect Team ID or Bundle ID
Associated Domains not properly configured in Xcode
iOS hasn’t updated AASA cache yet

Solutions:

# 1. Verify file accessibility
curl -v https://yourdomain.com/.well-known/apple-app-site-association

# 2. Check Team ID
# Go to Apple Developer → Membership → Team ID

# 3. Clear iOS cache (requires app reinstallation)
# Delete app → Reinstall from Xcode

Issue 2: Some Paths Don’t Trigger Deep Links

Checklist:

Confirm paths configuration correctly uses wildcards *
Check if NOT rules exclude that path
Verify URL fully matches (including trailing slash)

Issue 3: AASA Update Hasn’t Taken Effect

Force Update Methods:

Update app version number and republish
Recommend users delete and reinstall the app
Wait for iOS automatic update cycle (maximum 24 hours)

Best Practices

1. Path Planning

Use explicit path patterns, avoid overly loose wildcards
List specific paths first, then use wildcards
Use NOT to exclude API or admin interface paths

2. Security Considerations

Regularly check AASA file accessibility
Ensure SSL certificates are valid and not expired
Don’t include sensitive information in AASA files

3. Testing Process

Validate in test environment before production deployment
Use TestFlight for beta testing
Prepare rollback plan (keep backup of old AASA)

4. Monitoring and Maintenance

Set up monitoring alerts to track AASA file availability
Log the time and content of each AASA update
Regularly use Apple’s validation tool to check configuration

Conclusion

Properly configuring and updating the .well-known/apple-app-site-association file is the key step to implementing iOS Universal Links. While iOS’s update mechanism requires some time, by following the methods and best practices introduced in this article, you can ensure the reliability of your deep link configuration and provide users with a smooth app experience.

Key Takeaways:

AASA file must be served via HTTPS in the .well-known directory
Properly configure Team ID, Bundle ID, and paths rules
Use Apple’s official tool to validate configuration
Publishing app updates triggers iOS to recheck AASA
Regularly monitor and maintain AASA file accessibility

After mastering these techniques, you’ll be able to effectively manage your iOS app’s deep link configuration, ensuring users get the best experience no matter where they click links.

How to Update iOS App Deep Link Configuration: Complete AASA Guide