A Flutter ticketing app's shared event link opens the browser instead of the app; how do you diagnose it on Android and iOS?

## Split the problem first A verified link has two halves, and they fail differently: - The **app side**: the Android intent filter or the iOS Associated Domains entitlement, Flutter's deep-linking flag, and a router that can handle the path. - The **site side**: the association file on the domain, which the platform fetches to decide whether the domain trusts the app. A direct launch tests only the first half. The Flutter cookbook states this for Android: the `adb shell am start` command launches the app even if the web files are not present. So: 1. Run `adb shell am start -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d "https://tickets.example.com/events/42" <package>`, or on a Simulator `xcrun simctl openurl booted https://tickets.example.com/events/42`. 2. If the event page does **not** appear, fix the app side first: filter, entitlement, flag or router. 3. If it **does** appear, the app side is fine and the failure is verification; test by tapping the link in another app, such as a note or a chat message, because that is the path users take. ## Android causes | Symptom | Likely cause | |---|---| | store installs open the browser, local builds work | `sha256_cert_fingerprints` holds the upload key; Play App Signing signs installs with Google's app signing key | | no build ever verifies | intent filter lacks `android:autoVerify="true"`, or the `<data>` host differs from the domain | | verification fails intermittently or everywhere | `assetlinks.json` is not served over HTTPS at `/.well-known/assetlinks.json`, or the request is redirected | | only a debug build on one device fails | the build is signed with a debug key not listed, or Supported web addresses must be enabled by hand for a sideloaded build | On Android 12 and later, `adb shell pm get-app-links <package>` shows the verification state per domain, which turns guessing into a lookup. ## iOS causes - **Wrong app identifier**: `appIDs` must be `<team id>.<bundle id>`; a flavor with a different bundle ID needs its own entry. - **Path excluded**: `components` must match `/events/42`; a pattern for `/event/*` does not. - **Entitlement missing or wrong**: `applinks:tickets.example.com` must be in the Associated Domains capability of the signed build; personal teams cannot use it. - **Apple's CDN**: iOS fetches the file through Apple's content delivery network, and it can take up to 24 hours before a new or changed file is picked up. Apple's alternate developer mode bypasses the CDN during development. - **File details**: named `apple-app-site-association` with no `.json` extension, served over HTTPS from `/.well-known/`. ## When Flutter itself sends the link back The iOS embedding forwards an https link to the framework and asks whether it was handled. The framework offers the route information to every `WidgetsBindingObserver`: a `Router`'s route information provider, such as go_router's, or `WidgetsApp`'s navigator handling. If none of them accepts it, the engine **reopens the URL with the system**, which means Safari. Two related checks: - Is anything in the Dart app able to accept pushed route information, a `Router` or a `WidgetsApp` navigator? - Is the deep-linking flag still enabled? With `FlutterDeepLinkingEnabled` set to `NO`, the engine does not forward the link to Dart at all, so only a plugin can handle it. So an iOS link that briefly opens the app and then lands in Safari points at the Flutter side, not at the association file. On Android, the equivalent symptom is the app opening on its home screen or on the router's error page, because the intent was delivered but the path matched nothing. ## A worked example A ticketing app's event links worked for the QA team but opened the browser for everyone who installed from the store. The QA builds were signed locally with the upload key, whose fingerprint was the only one in `assetlinks.json`. Store installs are re-signed by Play App Signing with Google's key, so Android found no matching fingerprint and left the links to the browser. Adding the app signing key's SHA-256 from the Play Console fixed store installs without breaking QA builds. ## Tools that shorten the search - **DevTools > Deep Links** validates the Android manifest and `assetlinks.json` and, since Flutter 3.27, the iOS entitlements and `apple-app-site-association`, with instructions for each error. - **go_router's `debugLogDiagnostics: true`** prints the location the router received, which settles whether the path reached Dart intact. - **A cold and a warm test**: launch the link with the app killed and again with it in the background, because the two travel different code paths.