AASA File Format for iOS: Complete Developer Guide

What is AASA and Why It Exists

The Apple App Site Association (AASA) file is a JSON configuration file that enables iOS apps to claim ownership of your website domains. Without this file, iOS apps can open your website links, but users won't get the seamless experience of being directed directly to app content—they'll see a web page instead.

AASA is the foundation of Universal Links, Apple's solution for deep linking. It works by establishing a cryptographic connection between your website and your app, proving that both entities are owned by the same organization. This trust relationship is essential for Apple's strict security model.

When users tap a link to your domain, iOS checks for your AASA file. If it finds the correct configuration and your app is installed, iOS opens the app directly to the specified content. If the app isn't installed, the link opens normally in Safari.

AASA JSON Format Reference

Here's a complete AASA file structure with annotations explaining each section:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "9ABC123DEF.com.example.myapp",
        "paths": [
          "/product/*",
          "/account/profile",
          "NOT /static/*"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["9ABC123DEF.com.example.myapp"]
  }
}

applinks vs webcredentials Sections

Your AASA file can contain two main sections, each serving different purposes:

Version Differences: iOS 13+ vs Legacy

Apple introduced significant changes to AASA in iOS 13. Here's how they differ:

For modern app development, focus on the iOS 13+ format. If you need to support older iOS versions, structure your AASA to be backward compatible while leveraging newer features.

Path Patterns and Wildcards

Path patterns are how you tell iOS which URLs your app should handle. Understanding the pattern matching rules is critical:

"paths": [
  "/product/*",           // Wildcard - matches any substring
  "/account/profile",     // Exact path match
  "/posts/*/comments",    // Multi-level wildcards
  "NOT /admin/*",         // Exclude paths from matching
  "NOT /login",           // Exclude specific routes
  "/?*",                  // Match root and all subpaths
  "/checkout/success/*"   // Deep path matching
]

Hosting Requirements

Your AASA file must be hosted correctly for iOS to find and validate it:

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

Content-Type: application/json

Complete AASA Example

Here's a production-ready AASA configuration:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABC123DEF9.com.example.app",
        "paths": [
          "/product/*",
          "/order/*",
          "/account/*",
          "/referral/*",
          "NOT /admin/*",
          "NOT /api/*"
        ]
      },
      {
        "appID": "ABC123DEF9.com.example.app.beta",
        "paths": ["/beta/*"]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "ABC123DEF9.com.example.app",
      "ABC123DEF9.com.example.app.beta"
    ]
  }
}

Validating Your AASA File

After creating your AASA file, validate it before deploying. Invalid AASA files won't throw errors—they'll silently fail. Here are the validation steps:

Troubleshooting Common Issues

Here are solutions to the most common AASA problems:

Building on AASA: Next Steps

Now that you understand AASA, explore related deep linking topics:

Summary

The AASA file is essential for iOS deep linking. By understanding its format, hosting requirements, and path patterns, you can create reliable universal links that seamlessly direct users to your app content. Remember:

• Host AASA at .well-known/apple-app-site-association with HTTPS
• Ensure valid JSON and application/json Content-Type
• Use appID format: TeamID.bundleIdentifier
• Define paths carefully with wildcards and NOT exclusions
• Validate before deploying using our validator tool