Universal Links & App Links: The Complete Deep Linking Guide

Seamless mobile routing is critical for onboarding, marketing campaign conversions, email re-engagement, and cross-platform authentication flows.

However, configuring native deep linking across iOS (Apple Universal Links) and Android (Android App Links) involves strict HTTPS hosting requirements, domain association files, SHA-256 certificate fingerprints, and nuanced operating system routing behaviors.

This guide provides a comprehensive, production-ready blueprint for configuring and verifying modern mobile deep link architectures.

---

1. Custom URL Schemes vs. Universal Links

Feature	Custom URL Schemes (myapp://)	Universal Links / App Links (https://)
Protocol	Custom URI (myapp://product/123)	Standard HTTPS (https://myapp.com/product/123)
Security	Vulnerable to URI hijacking by other apps	Cryptographically verified via server association
Web Fallback	Shows broken dialog if app not installed	Seamlessly opens webpage in browser if app absent
In-App Browsers	Frequently blocked inside WeChat/Instagram	Supported across modern webviews

---

2. Apple Universal Links: The apple-app-site-association (AASA)

Apple requires an unencrypted JSON document named apple-app-site-association hosted at https://yourdomain.com/.well-known/apple-app-site-association.

AASA File Format (iOS 13+ Modern Syntax)

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.company.myapp",
          "ABCDE12345.com.company.myapp.beta"
        ],
        "components": [
          {
            "/": "/products/*",
            "?": { "utm_source": "mobile" },
            "comment": "Matches all product paths with mobile utm tracking"
          },
          {
            "/": "/auth/callback",
            "comment": "Handles OAuth authentication redirects"
          },
          {
            "/": "/admin/*",
            "exclude": true,
            "comment": "Prevents opening admin pages in native mobile app"
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCDE12345.com.company.myapp"]
  }
}

Critical AASA Hosting Rules

1. Zero Redirects: The URL must return HTTP 200 OK directly without HTTP 301 or 302 redirects.
2. Content-Type: Must be served with Content-Type: application/json.
3. No File Extension: Must be named exactly apple-app-site-association without .json.

---

3. Android App Links: assetlinks.json

Android uses Digital Asset Links to cryptographically tie web domains to APK signing keys.

assetlinks.json Structure

Hosted at https://yourdomain.com/.well-known/assetlinks.json:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.company.myapp",
      "sha256_cert_fingerprints": [
        "14:6D:E9:7F:0F:52:CC:45:25:4E:60:4B:92:4B:92:49:14:6D:E9:7F:0F:52:CC:45:25:4E:60:4B:92:4B:92:49"
      ]
    }
  }
]

Extracting Your Production SHA-256 Fingerprint

Run the following terminal command on your release keystore:

keytool -list -v -keystore my-release-key.jks -alias my-key-alias

Or copy the App Signing Certificate SHA-256 fingerprint directly from Google Play Console (Release > Setup > App Integrity).

Generate Both in Seconds: Use our Deep Link & Universal Links Studio to visually configure your Team ID, package names, path rules, and generate valid AASA & assetlinks.json files instantly.

---

4. Android AndroidManifest.xml Configuration

To enable auto-verification on Android 12+, declare android:autoVerify="true" inside your <intent-filter>:

<activity
    android:name=".MainActivity"
    android:exported="true">
    
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="https" android:host="yourdomain.com" android:pathPrefix="/products" />
        <data android:scheme="https" android:host="yourdomain.com" android:pathPrefix="/auth" />
    </intent-filter>
</activity>

---

5. Testing & Troubleshooting Checklist

• Check AASA validity using Apple’s official CDN: https://app-site-association.cdn-apple.com/a/v1/yourdomain.com.
• Test Android assetlinks via Google’s API: https://digitalassetlinks.googleapis.com/v1/statements:check?source.web.site=https://yourdomain.com&relation=delegate_permission/common.handle_all_urls&target.android_app.package_name=com.company.myapp.
• Verify test links with dynamic QR codes generated in our Deep Link Studio.