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.

A short link opens the app but nothing happens

The app launches and sits on whatever screen it was already showing. The same link written the long way works.

Your app is reading the URL it was handed and routing on the path. That works for /merchant/abc123, which says “merchant”. A short link is the same route written as a code, /imbwmum/abc123, and nothing in it says “merchant”, nor can the code be worked out on the device. Your app sees a first segment it has never heard of and does nothing.

Ask Tolinku what the link means before routing it:

const link = await Tolinku.links.resolve(url);
if (link) {
  route(link.deep_link_path); // "/merchant/abc123"
}

links.resolve is on every SDK. A readable URL comes back unchanged, so you can resolve every incoming link rather than guessing which kind you have.

This only affects apps that parse the path themselves. It does not affect the web, where the link is resolved before the page is served, and it does not affect deferred links, which arrive already resolved.

Analytics numbers seem off

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.

Custom domain not working

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.

API returns 401 Unauthorized

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.

API returns 403 with FEATURE_GATED

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.

API returns 403 with USAGE_EXCEEDED

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

Solutions:

Upgrade to a higher tier.
If you have a billing cap set, remove or raise it.
Wait for the next billing cycle (quotas reset monthly).

SDK not tracking events

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.

Deferred deep link not claimed

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.

Webhook not receiving events

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.