![\"Tolinku](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/screenshot-referrals-1772819416568.png\")
\nThe referrals page with stats cards, referral list, and leaderboard tabs.<\/em><\/p>\n\n\n\nThe Referral Link Lifecycle<\/h2>\n\n\n\n
A referral deep link goes through five distinct phases:<\/p>\n\n\n\n
- \n
- Generation<\/strong>: A unique referral code is created and embedded in a shareable URL<\/li>\n
- Distribution<\/strong>: The referrer shares the link via messaging, social media, or email<\/li>\n
- Click handling<\/strong>: The link is opened, the click is tracked, and the user is routed to the right destination<\/li>\n
- Attribution<\/strong>: The new user installs and opens the app, and the system matches them back to the referral<\/li>\n
- Reward fulfillment<\/strong>: Both parties receive their rewards once the required action is completed<\/li>\n<\/ol>\n\n\n\n
Let's examine each phase in detail.<\/p>\n\n\n\n
![\"User](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/referral-deep-links-sharing.jpeg\")
Photo by Thought Catalog on Pexels<\/figcaption><\/figure>\n\n\n\n Phase 1: Generating the Referral Link<\/h2>\n\n\n\n
When a user taps "Invite a Friend" in your app, the SDK calls your deep linking platform to generate a unique referral code. In Tolinku<\/a>, this happens through a single API call:<\/p>\n\n\n\n
POST \/v1\/api\/referral\/create\n{\n "user_id": "user_123",\n "user_name": "Jane Doe",\n "metadata": { "source": "share_screen" }\n}\n<\/code><\/pre>\n\n\n\nThe platform generates a 10-character code using cryptographically random bytes, producing something like
XKCD7B2MNQ<\/code>. This code gets embedded in a URL:<\/p>\n\n\n\nhttps:\/\/your-domain.tolinku.com\/ref\/XKCD7B2MNQ\n<\/code><\/pre>\n\n\n\nA few things happen behind the scenes during generation:<\/p>\n\n\n\n
- \n
- Deduplication<\/strong>: If the user already has an active (pending) referral, the existing code is returned instead of creating a new one<\/li>\n
- Rate limiting<\/strong>: A configurable per-user cap prevents abuse. If the limit is reached, the API returns a 400 error<\/li>\n
- Event tracking<\/strong>: A
referral_created<\/code> event fires, incrementing the referrer's analytics<\/li>\n- Webhook dispatch<\/strong>: A
referral.created<\/code> webhook notifies your backend with the code, referrer ID, and full URL<\/li>\n<\/ul>\n\n\n\nYou can configure referral settings<\/a> per Appspace, including expiration windows (1 to 365 days), per-user limits, and custom milestones.<\/p>\n\n\n\n
![\"Tolinku](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/referral-automation-settings.png\")
Referral configuration in the Tolinku dashboard with expiration, milestones, and reward settings<\/figcaption><\/figure>\n\n\n\n Phase 2: Sharing the Link<\/h2>\n\n\n\n
Once the referral URL is generated, the user shares it. The format of the link matters more than you might think.<\/p>\n\n\n\n
A referral deep link needs to work across every sharing channel: iMessage, WhatsApp, Twitter\/X, email, SMS, even copied and pasted into a notes app. The link itself is a standard HTTPS URL, which means it renders properly as a tappable link in any context.<\/p>\n\n\n\n
When shared on social media or messaging apps, the link server responds with Open Graph meta tags<\/a> so the link renders with a rich preview: title, description, and image. This social preview can be configured per route in the Tolinku dashboard under OG & Social Previews<\/a>.<\/p>\n\n\n\n
Phase 3: Click Handling and Routing<\/h2>\n\n\n\n
This is where the technical complexity lives. When the referred user taps the link, several things happen within milliseconds:<\/p>\n\n\n\n
Device Detection<\/h3>\n\n\n\n
The link server parses the
User-Agent<\/code> header to determine:<\/p>\n\n\n\n- \n
- Operating system<\/strong>: iOS, Android, or desktop<\/li>\n
- Device type<\/strong>: Phone, tablet, or computer<\/li>\n
- Browser<\/strong>: Safari, Chrome, in-app browser, etc.<\/li>\n<\/ul>\n\n\n\n
Click Tracking<\/h3>\n\n\n\n
Every click is recorded as an analytics event with:<\/p>\n\n\n\n
- \n
- IP address and approximate geolocation<\/li>\n
- Device and platform information<\/li>\n
- Campaign parameters (if any UTM tags are present)<\/li>\n
- The referral code from the URL path<\/li>\n<\/ul>\n\n\n\n
A
link.clicked<\/code> webhook<\/a> fires asynchronously, giving your backend real-time visibility into click activity.<\/p>\n\n\n\nRouting Decision<\/h3>\n\n\n\n
Based on the device, the server makes a routing decision:<\/p>\n\n\n\n
If the user has the app installed (and Universal Links or App Links are configured):<\/strong>\nThe operating system intercepts the link and opens it directly in the app. The referral code is passed as part of the deep link path (
\/ref\/XKCD7B2MNQ<\/code>), and the app handles it immediately. No attribution complexity here.<\/p>\n\n\n\nIf the user does not have the app (the common case for referrals):<\/strong>\nThis triggers the deferred deep linking<\/a> flow. The server needs to:<\/p>\n\n\n\n
- \n
- Store the referral context for later retrieval<\/li>\n
- Send the user to the appropriate app store<\/li>\n
- Ensure the context survives the install process<\/li>\n<\/ol>\n\n\n\n
Deferred Link Storage<\/h3>\n\n\n\n
Before redirecting to the app store, the server stores a deferred link record containing the referral path, a fingerprint derived from the user's IP and User-Agent, device signals (timezone, language, screen dimensions), and a unique referrer token.<\/p>\n\n\n\n
This record has a 24-hour time-to-live. If the user doesn't install the app within that window, the deferred link expires. For production deployments, these records are stored in Redis for fast retrieval; a memory-based fallback is available for development.<\/p>\n\n\n\n
App Store Redirect<\/h3>\n\n\n\n
The redirect strategy differs by platform:<\/p>\n\n\n\n
Android<\/strong>: The user is sent to the Google Play Store with a special
referrer<\/code> query parameter:<\/p>\n\n\n\nhttps:\/\/play.google.com\/store\/apps\/details?id=com.example.app&referrer=tolk_token=abc123def456\n<\/code><\/pre>\n\n\n\nThe Google Play Install Referrer API<\/a> preserves this token through the installation process, making it available to the app on first launch.<\/p>\n\n\n\n
iOS<\/strong>: The user is sent to the App Store. Since Apple doesn't offer an equivalent to Android's Install Referrer API, the token is stored server-side and matched using device signals after the app opens.<\/p>\n\n\n\n
Phase 4: Attribution After Install<\/h2>\n\n\n\n
This is the most technically challenging phase. The user has installed your app from the store. Now the app needs to "claim" the deferred deep link and extract the referral code.<\/p>\n\n\n\n
Android: Token-Based Matching<\/h3>\n\n\n\n
On Android, attribution is deterministic. Here's the flow:<\/p>\n\n\n\n
- \n
- The app launches for the first time<\/li>\n
- The SDK reads the install referrer using Google's Install Referrer API<\/li>\n
- It extracts the
tolk_token<\/code> value<\/li>\n- It calls the Tolinku API:
GET \/api\/deferred\/claim?token=abc123def456<\/code><\/li>\n- The server looks up the deferred link by token, marks it as claimed, and returns the original deep link path<\/li>\n
- The app receives
\/ref\/XKCD7B2MNQ<\/code> and knows this is a referral install<\/li>\n<\/ol>\n\n\n\nThis is a 1:1 deterministic match. There's no ambiguity, no false positives.<\/p>\n\n\n\n
iOS: Signal-Based Matching<\/h3>\n\n\n\n
On iOS, the matching is probabilistic but highly accurate. The process works like this:<\/p>\n\n\n\n
- \n
- The app launches for the first time<\/li>\n
- The SDK collects device signals: timezone, language, screen width, and screen height<\/li>\n
- It sends these signals along with the device's IP address to the Tolinku API<\/li>\n
- The server searches for unclaimed deferred links from the same IP within a configurable match window (default: 2 hours)<\/li>\n
- Each candidate is scored on a 4-point scale:<\/li>\n<\/ol>\n\n\n\n
- It calls the Tolinku API:
- Device type<\/strong>: Phone, tablet, or computer<\/li>\n
- Rate limiting<\/strong>: A configurable per-user cap prevents abuse. If the limit is reached, the API returns a 400 error<\/li>\n
- Distribution<\/strong>: The referrer shares the link via messaging, social media, or email<\/li>\n
![\"Tolinku](\"https:\/\/tolinku.com\/blog\/wp-content\/uploads\/2026\/03\/platform-platform-referrals.png\")