what is apple-app-site-association file

DrupalVIP Support

The apple-app-site-association (AASA) file is a crucial component for iOS app developers that creates a secure and verified link between a website and its associated iOS applications. It's often referred to as an AASA file.

Here's a breakdown of its purpose and how it works:

Purpose:

  • Universal Links: The primary purpose of the AASA file is to enable Universal Links. Universal Links allow users to tap a link to your website and, if your app is installed, be seamlessly redirected directly into the relevant content within your app, bypassing the Safari web browser. If the app isn't installed, the link opens your website in Safari as usual. This creates a much smoother and more integrated user experience.
  • Secure Association: It establishes a secure association between your domain and your app(s), allowing iOS to verify that a specific app is indeed authorized to handle links from that website. This prevents malicious apps from intercepting your URLs.
  • Shared Features: Beyond Universal Links, AASA also supports other features like:
    • Shared Web Credentials: Allows users to securely share login credentials between your website and your app.
    • Handoff: Enables users to seamlessly continue an activity from your website to your app (or vice versa) on a different device.
    • App Clips: Facilitates the use of App Clips, which are small parts of your app that can be launched quickly to perform a specific task without needing to download the full app.
  • Improved Discoverability: By allowing app content to be directly linked from the web, it can improve the discoverability of your app through web searches and social media.

How it Works:

  1. File Creation: You create a JSON file named apple-app-site-association (without any file extension). This file contains information about your app(s) and the specific URL paths on your website that your app can handle. It includes:

    • appID: A combination of your Apple Developer Team ID and your app's Bundle Identifier.

    • paths: An array of strings that specify which URL paths your app should handle. You can use wildcards (* or ?) for flexibility and even NOT to exclude specific paths.
    • Other optional keys for features like web credentials or App Clips.

  2. File Hosting: The AASA file must be hosted on your website at one of two specific locations:

    • https://yourdomain.com/apple-app-site-association
    • https://yourdomain.com/.well-known/apple-app-site-association (This is the recommended and preferred location as per Apple.)
    • Important Requirements:
      • It must be served over HTTPS with a valid SSL/TLS certificate.
      • It must not redirect to another location.

      • It should have a Content-Type header of application/json.
      • Its uncompressed size should not exceed 128KB.

  3. App Configuration (Xcode): In your Xcode project, you need to:

    • Enable the "Associated Domains" capability.

    • Add entries in the format applinks:yourdomain.com (or applinks:*.yourdomain.com for subdomains) to specify the domains your app is associated with.

  4. iOS Device Download: When a user installs or updates your app, their iOS device attempts to download the apple-app-site-association file from the domains listed in your app's associated domains. Starting with iOS 14, these requests are typically sent to an Apple-managed Content Delivery Network (CDN) for efficiency.

  5. Link Handling: When a user taps a universal link that matches a path specified in your AASA file:

    • If your app is installed and the association is verified, iOS will open the link directly within your app.
    • If your app is not installed, or if the association fails, the link will open in Safari.
    • If the user is already Browse your website in Safari and taps a universal link to a URL on the same domain, iOS will typically keep the user in Safari (unless a different subdomain is used for the universal link).

In essence, the apple-app-site-association file acts as a bridge, allowing your website to tell iOS which of its URLs should be handled by your native app, providing a more seamless and integrated user experience.