> ## Documentation Index > Fetch the complete documentation index at: https://learn.biq.li/llms.txt > Use this file to discover all available pages before exploring further. # Test and troubleshoot mobile links > Verify association files, installed-app routing, deferred installs, retries, and common failures. Mobile deep linking is in **Public Beta**. Emulator and simulator tests do not replace Google Play and TestFlight deferred-install tests. Test in layers. A successful API response cannot compensate for an invalid platform association, and a verified association cannot prove the store-install handoff. ## 1. Verify the public association files Open these exact URLs for the Mobile App's hostname: ```text theme={null} https://go.example.com/.well-known/apple-app-site-association https://go.example.com/.well-known/assetlinks.json ``` Each response must be direct HTTPS `200`, use `application/json`, stay within 128 KB, and contain the exact active app identifiers. Redirects between hostnames or from HTTP to HTTPS do not satisfy platform verification. Use **Workspace settings → Mobile Apps → your app → Verify public files** to compare the public documents with the expected Biqli configuration. ## 2. Verify Android App Links The installed build's signing certificate must appear in `assetlinks.json`. A locally signed debug build and a Google Play build normally have different certificates. When Play App Signing is enabled, include the App signing key certificate shown by Google Play for Play-delivered builds; include other fingerprints only for builds that must verify on the same domain. On Android 12 or later: ```bash theme={null} adb shell pm verify-app-links --re-verify com.example.app adb shell pm get-app-links com.example.app adb shell am start -W \ -a android.intent.action.VIEW \ -c android.intent.category.BROWSABLE \ -d "https://go.example.com/example" ``` Wait for asynchronous verification before reading the result. The hostname should report `verified` and the final command should launch your activity. Android 15 and later can periodically refresh association changes, but propagation can take up to seven days. Android 14 and earlier normally pick up changes when the app is installed or updated. Re-verification, reinstalling, and server caches can still delay a test. See [Verify Android App Links](https://developer.android.com/training/app-links/verify-applinks). ## 3. Verify iOS Universal Links Confirm the app has `applinks:go.example.com` in its signed associated-domains entitlement. Tap the link from Mail, Notes, or another application; typing it into Safari's address bar is not the same test. The app should receive an `NSUserActivityTypeBrowsingWeb` activity. Apple retrieves association files through its managed content-delivery network on iOS 14 and later. Apple states that its network requests a new file within 24 hours and installed devices may check for updates approximately weekly. Reinstall the app after the association is available when testing a changed entitlement or document. See [Supporting associated domains](https://developer.apple.com/documentation/xcode/supporting-associated-domains) and [Debugging Universal Links](https://developer.apple.com/documentation/technotes/tn3155-debugging-universal-links). ## 4. Test installed-app resolution Open a mobile-enabled short URL with the app installed. Confirm: * the operating system launches the correct app; * the SDK sends the HTTPS deep link; * the response is `exact_app_link` with exact confidence; * the route and allowed attribution values match the current link; and * the app rejects an unknown route safely. Also send a request without a deep link and verify that `none` is handled as a successful result. ## 5. Test Android deferred installation Use a Google Play internal test track. Uninstall the app, open the Biqli link on an eligible Android device, install from the Play page reached through that click, and launch the app. Expect `exact_install_referrer` on the first eligible resolution. A sideloaded APK, Android Studio installation, or emulator-only flow can test the installed App Link and API, but cannot prove that Google Play delivered the referrer. ## 6. Test iOS deferred installation Use a TestFlight or App Store build. Remove the app, open the link, select **Continue** on the Deep View, install the app, launch it, and select the explicit Biqli paste control. Expect `exact_handoff`. Test these negative cases too: * paste unrelated text and expect `invalidHandoffURL`; * let a handoff expire and expect no exact match; * deny consent when required and expect the SDK to stop before the request; * disconnect the device, start resolution, reconnect it, and retry on a later cold launch; and * reuse a completed handoff from a different installation and confirm it is rejected. ## Common failures | Symptom | Check | | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | Link opens a browser instead of Android app | `autoVerify`, exact hostname, manifest path, public `assetlinks.json`, and the installed build's SHA-256 certificate. | | Link opens Safari instead of iOS app | Signed associated-domains entitlement, exact hostname and path, public AASA, Apple cache timing, and whether the link was tapped from another app. | | Store opens but first launch returns `none` | The link was mobile-enabled at click time, app and domain were active, handoff had not expired, and the build came from the correct store path. | | iOS Paste reports `invalidHandoffURL` | The clipboard item is not the complete Biqli handoff URL, is stale, or was altered. Repeat the click and Continue flow. | | Resolver reports `transport` | Check connectivity and TLS. Keep startup non-blocking and retry the persisted request on a later launch. | | Resolver returns `handoff_mismatch` | Do not combine a handoff and direct deep link from different clicks. Clear the invalid input and begin a new link flow. | | Resolver returns `header_mismatch` | Ensure body `platform` and `sdkVersion` exactly match the SDK headers. | | Resolver returns `invalid_probabilistic_domain` | Configure the exact verified HTTPS domain on the Mobile App and SDK, or disable probabilistic matching. | Include the `X-Biq-Request-Id`, approximate UTC time, platform, SDK version, and match/error code when contacting support. Never send a mobile publishable key, handoff token, signed receipt, or complete attribution payload in a public support channel.