Troubleshooting

Common issues when setting up Universal Links, App Links, and match().

Universal Links not working on iOS

Check Associated Domains is added in Xcode.
Check apple-app-site-association is accessible: https://yourapp.flku.dev/.well-known/apple-app-site-association
Must open the link from another app (Messages, Safari), not by typing it in the browser address bar.
Re-install the app after adding Associated Domains.
Flutter apps: if the app opens but Dart never gets the URL (wrong screen, browser flash, intermittent cold starts), see Universal Links not opening the app on iOS (Flutter).

Check the intent filter is in AndroidManifest.xml with android:autoVerify="true".
Check assetlinks.json is accessible: https://yourapp.flku.dev/.well-known/assetlinks.json
Verify the SHA-256 fingerprint matches your release keystore.
Run: adb shell pm get-app-links your.package.name

Make sure you open the link in Safari or Chrome (do not type the URL manually in the address bar).
Fingerprint attribution expires 24 hours after the original click. Tap the link and open the app within that window.
Call reset() and try again. Correct forms:
- Flutter: await Flinku.reset()
- iOS: Flinku.reset()
- Android: Flinku.reset(context)
- React Native: await flinku.reset()
- Capacitor: await flinku.reset()
- Unity: FlinkuSDK.Instance.Reset()
Check the subdomain in your baseUrl matches your project subdomain exactly.

The server consumes a deferred match on first successful return, then allows the same match again for 5 minutes (grace window for app restarts). After that window the server will not return it again. SDK-local dedup also prevents re-firing on subsequent cold starts once cached.
Call reset() during development to clear the cached match result only (does not clear stored user id or pending referral attribution; this changed in 0.6.0). Correct forms:
- Flutter: await Flinku.reset()
- iOS: Flinku.reset()
- Android: Flinku.reset(context)
- React Native: await flinku.reset()
- Capacitor: await flinku.reset()
- Unity: FlinkuSDK.Instance.Reset()
If referral or match state is still wrong during testing, call resetAll() to wipe all Flinku local state. Clears everything reset() clears, plus the stored user id, referral project id, all pending referral records, and any tracked-once markers. Testing only — do not call in production. Calling it in production destroys real referral attribution. Added in 0.7.0. Correct forms:
- Flutter: await Flinku.resetAll()
- iOS: Flinku.resetAll()
- Android: Flinku.resetAll(context)
- React Native: await flinku.resetAll()
- Capacitor: await flinku.resetAll()
- Unity: FlinkuSDK.Instance.ResetAll()

Installing over ADB (npm run android, Android Studio Run, or adb install) exercises the fingerprint matching path only.
The Play Install Referrer API is only available when the app is installed from the Google Play Store, not from sideload or ADB installs. Client support: native Android SDK; Flutter 0.8.0-beta.1 prerelease only (stable 0.7.2 does not include it). React Native, Capacitor, and Unity do not read Install Referrer. To use it on Flutter, add flinku_sdk: 0.8.0-beta.1 to pubspec.yaml — not ^0.8.0-beta.1, because pub does not resolve prereleases from a caret — then rebuild the app (the beta is a Flutter plugin; hot reload is insufficient).
To verify the Play Install Referrer attribution path end-to-end, distribute a build that uses a supported SDK through Google Play Internal Testing (or another Play track), install from the Play Store, then run your deferred deep link test flow.