Deep linking · Research note
assetlinks.json and apple-app-site-association (AASA) Compared
Android and Apple solve the same problem with different files. Both live under /.well-known/ on every host and both refuse redirects, but they identify the app differently, match paths in different places and reach devices on different schedules. Most cross-platform bugs come from assuming one behaves like the other.
Scope and limits
Compiled from Android and Apple developer documentation read on October 28, 2026. Timings are as each platform documents them, not measurements.
Side by side
| Aspect | assetlinks.json (Android) | apple-app-site-association (Apple) |
|---|---|---|
| Location | /.well-known/assetlinks.json | /.well-known/apple-app-site-association, no extension |
| Transport | https, application/json, no redirects | https with a valid certificate, no redirects |
| Scope | One file per host domain | One file per domain or subdomain in the entitlement |
| Root of the file | Array of statements | Object with services: applinks, webcredentials, appclips |
| App identity | Package name plus SHA-256 signing fingerprints | Team ID prefix plus bundle identifier |
| Which URLs | Intent filters in the manifest; optional dynamic rules on Android 15 and later | Components in the file: path, query, fragment, exclude |
| Who fetches it | The device's verifier, for each host in the manifest | Apple's content delivery network, since iOS 14 and macOS 11 |
| Update timing | Android 15 and later: up to seven days; Android 14 and lower: no scheduled re-verification | Apple's network within 24 hours; devices about once a week |
| Development testing | pm verify-app-links --re-verify, Digital Asset Links API | Alternate mode such as ?mode=developer, swcutil, Developer Mode diagnostics |
| Classic failure | Redirect on the file host, or the wrong signing fingerprint | Blocked or redirected file, or a mix of old and new formats |
Identity: a key versus an account
The biggest conceptual difference is how each file names the app. Android ties the link to the certificate that signs the build, so the file changes when signing changes, and with Play App Signing it must list the key Google uses. Apple ties the link to the developer account's Team ID and the bundle identifier, so signing changes do not touch the file, but a new bundle identifier does. A rebrand or an app split, for example when a brand separates its casino and sportsbook apps, means updating both files, each for its own reason.
Path rules live in different places
On Apple, the file carries the path rules; on Android, the manifest does, with the file only granting trust. Android's dynamic rules narrow this on Android 15 and later, evaluated top to bottom with the first match winning, but they cannot add hosts beyond the manifest. Apple's example lists a specific exclusion before a broader pattern, and that order is the safe habit for both. Practically, a path that should stay on the web, such as a safer gambling page, needs an Apple exclusion and an Android rule or a manifest that does not claim it. Where the Android manifest rules live is shown in the Android App Links guide.
Caching and timing
Apple's network sits between your server and devices: "Apple's content delivery network requests the apple-app-site-association file for your domain within 24 hours. Devices check for updates approximately once per week after app installation." Android 15 and later re-check in the background, and "Changes can take up to seven days to propagate to all end-user devices." On Android 14 and lower, "The system does not perform periodic background re-verification." Plan file changes days ahead of a campaign, and keep old patterns valid while the new file spreads.
Blind spots in testing
- Testing iOS in developer mode bypasses Apple's network, so a test can pass while the public file is still blocked for Apple's content delivery network.
- Testing a debug build on Android checks the debug fingerprint, not the release or Play signing key.
- Testing only the main host misses help, promotion and market subdomains.
Paste either file into the association file linter for a shape check, then follow the assetlinks.json guide and the Apple App Site Association (AASA) guide for hosting.
Questions
Do both files need updating when a brand splits its casino and sportsbook apps?
Yes, for different reasons: Android needs the new package and its signing fingerprint, Apple needs the new Team ID and bundle identifier entry.
Which file holds the path rules?
On Apple the association file does; on Android the manifest does, with dynamic rules narrowing it on Android 15 and later.
Can the same pattern syntax be copied between the files?
Partly. Both use / for paths, ? for query items, # for fragments and an exclude flag, but Android's dynamic rules only apply on Android 15 and later with Google services, and they can never add hosts that the manifest does not already declare.
Sources
- Android Developers, Configure website associations and dynamic rules, last updated October 23, 2026.
- Android Developers, Verify App Links, last updated October 23, 2026.
- Apple Developer, Supporting associated domains, no date shown.
- Apple Developer, applinks (Bundle Resources), no date shown.
- Apple Developer, TN3155: Debugging universal links, latest revision May 15, 2025.
How we choose and date sources: data sources.