Troubleshooting Android Deep Links

App Links show a disambiguation dialog

If Android shows a “Open with…” dialog instead of opening your app directly, verification has failed.

Check the assetlinks.json file

Visit https://your-domain/.well-known/assetlinks.json in a browser. Verify:

• The file loads without redirects.
• The package_name matches your app’s package name exactly.
• The sha256_cert_fingerprints array includes the correct fingerprint.
• Content-Type is application/json.

Use Google’s Digital Asset Links Tester to validate.

Check the SHA-256 fingerprint

The most common cause of verification failure is a fingerprint mismatch.

If using Google Play App Signing:

• Go to Google Play Console > Setup > App signing.
• Copy the SHA-256 certificate fingerprint under “App signing key certificate”.
• This is the key Google uses to sign your APK. It is different from your upload key.

If signing locally:

keytool -list -v -keystore your-release-key.jks -alias your-alias

Copy the SHA256: line.

Paste the fingerprint into Appspace Settings > Android > SHA-256 Certificate Fingerprint(s).

Caution

If you use Google Play App Signing, the upload key fingerprint will not work. You must use the app signing key fingerprint from the Play Console.

Check the intent filter

In your AndroidManifest.xml:

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="your-domain.com" />
</intent-filter>

Common mistakes:

• Missing android:autoVerify="true".
• Wrong host (typo, missing subdomain).
• Missing DEFAULT or BROWSABLE category.

Re-verify App Links

After fixing the issue, force re-verification:

adb shell pm verify-app-links --re-verify com.example.myapp

Check the result:

adb shell pm get-app-links com.example.myapp

Look for your domain with status verified.

Links not opening the app at all

App not installed

If the app is not installed, links open in the browser. This is expected behavior. The user sees your landing page.

Wrong Activity

Ensure the intent filter is on the Activity that should handle deep links, and that the Activity has android:exported="true".

Intent data not received

In your Activity, read the deep link from the Intent:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    val uri = intent.data  // This is the deep link URL
}

Also handle onNewIntent for when the Activity is already running:

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    val uri = intent.data
}

Deferred deep linking not working

Token-based claiming

• The referrer string contains a tolk_token parameter. Make sure you are parsing for tolk_token (not token, ul_token, or other names).
• Log the raw referrer string from the Install Referrer API to verify the token is present and correctly formatted (e.g. tolk_token=abc123).
• Ensure the extracted token is being passed to Tolinku.deferred.claimByToken(token).
• The referrer token is only available via the Install Referrer API. If you are not using the Play Store for distribution (e.g. sideloading), token-based matching will not work. Use signal-based claiming as a fallback.
• Some devices or Play Store versions may not support the Install Referrer API.

Signal-based claiming

• Pass a valid Context to claimBySignals so the SDK can collect screen dimensions.
• VPNs or IP changes between click and install reduce matching accuracy.
• Call claimBySignals on the very first app open, before navigating the user.

Multiple fingerprints

You can add multiple SHA-256 fingerprints in Appspace Settings (comma-separated). This is useful for:

• Debug and release certificates during development.
• Google Play App Signing key plus your upload key.
• Multiple signing configurations (e.g. different build variants).

Testing checklist

1. assetlinks.json accessible at /.well-known/assetlinks.json (no redirects).
2. Package name and SHA-256 fingerprint set in Appspace Settings.
3. Intent filter with autoVerify="true" in AndroidManifest.xml.
4. Activity has android:exported="true".
5. App installed on device (run adb shell pm get-app-links to check status).
6. Re-verified with adb shell pm verify-app-links --re-verify.
7. SDK initialized with Tolinku.configure(apiKey = ..., context = ...) in Application.onCreate().