App linking

Mobile and PWA discovery files that mishandle the strict format requirements iOS, Android, and browsers enforce.

GET /.well-known/apple-app-site-association

iOS universal-links manifest (AASA). Apple is famously strict about the Content-Type, JSON validity, appID format (TEAMID.bundle.id), and the paths array. These modes break each of those expectations.

mode wrong-content-type (default; served as text/html), malformed-json (invalid JSON), bad-appid (missing TEAMID prefix or wrong format), path-mismatch (empty paths array).

details

GET /.well-known/assetlinks.json

Android App Links manifest. Android verifies app links by checking SHA-256 fingerprints, package_name, and relation strings against a strict schema. These modes break each of those.

mode wrong-fingerprint-format (default; fingerprint without colon delimiters), package-mismatch (fictional package_name), unknown-relation (invented permission relation string), malformed-json (truncated JSON array).

details

GET /manifest.webmanifest

PWA web app manifest. Wide tooling consumption — Chrome, Lighthouse, browser PWA installers all parse this and complain when it's wrong. Modes break required icons, start_url, display modes, colors, or name fields.

mode missing-icons (default; icons array empty), wrong-start-url (start_url points to a 404), contradictory-display (display: standalone with display_override: [browser, minimal-ui, fullscreen]), invalid-colors (theme_color: 'not-a-color', background_color: '#GGGGGG'), name-mismatch (name and short_name disagree about identity).

details

iOS, Android, and PWA installers all auto-discover or read these files from canonical paths. Each platform has its own strict format. Real-world bugs in app linking are common and frustrating to diagnose because the failure mode is usually silent: the OS simply doesn’t recognise the app as the handler for the URL, or the install prompt never appears.

Point your build pipeline’s link-verification step or your PWA tooling at these endpoints to confirm it surfaces the failure clearly rather than failing closed.