Common Issues

Links open in the browser instead of the app

Cause: Universal Links (iOS) or App Links (Android) are not configured correctly.

Solutions:

Verify your Bundle ID and Team ID (iOS) or package name and SHA-256 fingerprint (Android) in Appspace Settings.
Check that the route has Universal Link enabled (iOS routes must opt in individually).
Ensure the Associated Domains entitlement (iOS) or autoVerify intent filter (Android) is set up in your app.
Test the AASA file: visit https://your-domain/.well-known/apple-app-site-association in a browser.
Test the assetlinks file: visit https://your-domain/.well-known/assetlinks.json in a browser.
See Troubleshooting iOS and Troubleshooting Android for platform-specific steps.

Cause: Several factors can cause discrepancies.

Solutions:

Bot traffic. Enable bot detection in Appspace Settings (paid plans) to filter automated clicks.
Caching. Analytics are processed in ClickHouse with a slight delay (typically seconds, occasionally minutes during high traffic).
Date range. Check that your dashboard date range matches what you expect. The default is 30 days.
Timezone. ClickHouse stores events in UTC. If your dashboard shows a different timezone, the day boundaries may not match your local time.

Cause: DNS not propagated, or SSL certificate not issued.

Solutions:

Verify your CNAME record points to the correct target shown in Domains settings.
DNS changes can take up to 48 hours to propagate (usually faster).
Check that the domain shows a green Verified badge in the dashboard. If it shows Pending, the DNS record has not been detected yet.
Ensure there is no conflicting A record on the same subdomain.

Cause: Missing or invalid API key.

Solutions:

Include the key in the X-API-Key header (not as a query parameter).
Check that the key has not been revoked in the API Keys dashboard.
Verify the key prefix matches the environment: tolk_pub_ for publishable, tolk_sec_ for secret.

Cause: The feature requires a paid plan.

Solutions:

Referrals, audiences, A/B testing, and bot detection are only available on paid plans (Standard or higher).
Upgrade from the Billing & Plans page.

Cause: The Appspace has exceeded 110% of its plan’s click or API call quota.

Solutions:

Cause: Configuration issue or events not flushing.

Solutions:

Verify you called configure() or init() before any tracking calls.
Check that the API key is correct and active.
Events are batched (10 events or 5-second timer). Call flush() to force an immediate send.
Check the device’s network connectivity.
Enable debug mode in the SDK to see log output.

Cause: The matching window expired or signals did not match.

Solutions:

Signal-based matching (iOS) is probabilistic. It works best within minutes of the click. If the user installs hours later, the match may fail.
Token-based matching (Android) requires the Play Store referrer token. Ensure the install URL includes the referrer parameter and that your app parses the tolk_token value from the referrer string.
Check that the SDK calls claimBySignals or claimByToken on first app open.

Cause: Endpoint unreachable, incorrect URL, or event not subscribed.

Solutions:

Verify the webhook URL is publicly accessible over HTTPS.
Check that the webhook is subscribed to the event type you expect (e.g. link.clicked).
Look at the delivery log in Webhooks for error details and HTTP status codes.
Ensure your endpoint returns a 2xx status code within 10 seconds.