{"id":595,"date":"2026-03-25T09:00:00","date_gmt":"2026-03-25T14:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=595"},"modified":"2026-03-07T03:32:56","modified_gmt":"2026-03-07T08:32:56","slug":"deferred-deep-linking-for-referrals","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/deferred-deep-linking-for-referrals\/","title":{"rendered":"Using Deferred Deep Links for Referral Programs"},"content":{"rendered":"\n

A referral program only works if you can reliably answer two questions: who referred this new user, and did that new user actually complete the required action (install, sign up, first purchase)? Without those answers, you cannot trigger rewards accurately.<\/p>\n\n\n\n

Deferred deep links solve the first question for mobile apps. They carry the referrer's identity through the install, even when the referred user does not have your app installed at the moment they tap the invite link. This guide covers the full flow from link generation to reward triggering.<\/p>\n\n\n\n

Why Regular Links Are Not Enough<\/h2>\n\n\n\n

Suppose User A shares a simple link to your app: https:\/\/myapp.com<\/code>. User B taps the link on their phone, lands on the App Store, installs the app, and opens it.<\/p>\n\n\n\n

When the app opens, there is no way to know User B came from User A's link. The App Store stripped all context. The app sees a cold open. No referral is recorded. No reward is triggered.<\/p>\n\n\n\n

A regular App Store link cannot carry the referral code through the install. That is the gap that deferred deep links fill.<\/p>\n\n\n\n

The Complete Referral Link Flow<\/h2>\n\n\n\n

Here is how the flow works with Tolinku:<\/p>\n\n\n\n

    \n
  1. User A (the referrer) generates or receives a unique referral link, for example: https:\/\/tolinku.link\/ref\/ABC123<\/code><\/li>\n
  2. User A shares this link via text, social media, or in-app sharing.<\/li>\n
  3. User B (the invited friend) taps the link. Tolinku records the click, including the referral code ABC123<\/code>, the timestamp, and device signals.<\/li>\n
  4. User B is redirected to the App Store (or Google Play). On Android, the referral code travels through the Play Install Referrer. On iOS, it is stored server-side for fingerprint matching.<\/li>\n
  5. User B installs and opens the app for the first time.<\/li>\n
  6. On first open, Tolinku's SDK matches the install to the click and returns the deep link data, including the referral code.<\/li>\n
  7. Your app reads the referral code, attributes the install to User A, and triggers the reward logic.<\/li>\n<\/ol>\n\n\n\n

    The referral code survives the app store gap because it is stored in Tolinku's system at click time and retrieved at first-open time. It never needs to pass through the App Store itself.<\/p>\n\n\n\n

    Setting Up Referral Links in Tolinku<\/h2>\n\n\n\n

    \"Tolinku<\/p>\n\n\n\n

    You can create referral links through the API or the dashboard.<\/p>\n\n\n\n

    Via API<\/h3>\n\n\n\n
    curl -X POST https:\/\/api.tolinku.com\/v1\/links \\\n  -H "Authorization: Bearer tolk_sec_your_key" \\\n  -H "Content-Type: application\/json" \\\n  -d '{\n    "path": "\/referral\/ABC123",\n    "appspaceId": "your_appspace_id",\n    "params": {\n      "referral_code": "ABC123",\n      "referrer_user_id": "user_42",\n      "utm_source": "referral",\n      "utm_medium": "in-app-share"\n    },\n    "fallbackUrl": "https:\/\/yourapp.com\/invite\/ABC123"\n  }'\n<\/code><\/pre>\n\n\n\n
    The fallbackUrl<\/code> is where users land on desktop or unsupported platforms. A web landing page that explains the referral and links to the App Store\/Play Store is typical.<\/p>\n\n\n\n
    For programmatic link generation at scale (one link per user, potentially millions of users), use the API documentation<\/a> for batch link creation patterns.<\/p>\n\n\n\n
    Generating Links Per User<\/h3>\n\n\n\n
    Most referral programs generate one unique link per referrer. This is preferable to reusing a single referral code, because it gives each referrer a distinct share link, which is cleaner for UX and easier to attribute.<\/p>\n\n\n\n
    In your backend, generate the link when the user first visits the referral or share screen:<\/p>\n\n\n\n
    \/\/ Server-side Node.js example\nasync function getOrCreateReferralLink(userId) {\n  const existing = await db.referralLinks.findOne({ userId });\n  if (existing) return existing.url;\n\n  const code = generateReferralCode(); \/\/ e.g., first 6 chars of hashed userId\n\n  const response = await fetch("https:\/\/api.tolinku.com\/v1\/links", {\n    method: "POST",\n    headers: {\n      "Authorization": `Bearer ${process.env.TOLINKU_SECRET_KEY}`,\n      "Content-Type": "application\/json"\n    },\n    body: JSON.stringify({\n      path: `\/referral\/${code}`,\n      appspaceId: process.env.TOLINKU_APPSPACE_ID,\n      params: {\n        referral_code: code,\n        referrer_user_id: userId,\n        utm_source: "referral",\n        utm_medium: "in-app-share"\n      },\n      fallbackUrl: `https:\/\/yourapp.com\/invite\/${code}`\n    })\n  });\n\n  const link = await response.json();\n  await db.referralLinks.create({ userId, code, url: link.shortUrl });\n  return link.shortUrl;\n}\n<\/code><\/pre>\n\n\n\n
    Return the short URL to the client for sharing.<\/p>\n\n\n\n
    \"person
    Photo by Dustin Belt<\/a> on Unsplash<\/a><\/figcaption><\/figure>\n\n\n\n
    Handling the Referral on First Open<\/h2>\n\n\n\n
    In your mobile app, after Tolinku's SDK resolves the deferred link, check for a referral code:<\/p>\n\n\n\n
    iOS (Swift)<\/h3>\n\n\n\n
    Tolinku.shared.resolveDeferred { result in\n    DispatchQueue.main.async {\n        InstallState.hasResolvedFirstOpen = true\n        switch result {\n        case .success(let deepLink):\n            if let code = deepLink.referralCode {\n                self.attributeReferral(code: code)\n            }\n            self.route(to: deepLink)\n        case .failure:\n            self.showDefaultOnboarding()\n        }\n    }\n}\n\nfunc attributeReferral(code: String) {\n    \/\/ Call your backend to record the referral\n    API.recordReferral(code: code, newUserId: currentUser.id) { result in\n        \/\/ Handle success or failure\n    }\n}\n<\/code><\/pre>\n\n\n\n
    Android (Kotlin)<\/h3>\n\n\n\n
    Tolinku.shared.resolveDeferred(this) { result ->\n    runOnUiThread {\n        InstallState.markFirstOpenResolved(this)\n        result.onSuccess { deepLink ->\n            deepLink.referralCode?.let { code ->\n                attributeReferral(code)\n            }\n            routeTo(deepLink)\n        }.onFailure {\n            showDefaultOnboarding()\n        }\n    }\n}\n\nfun attributeReferral(code: String) {\n    \/\/ Call your backend to record the referral\n    api.recordReferral(code, currentUser.id) { result ->\n        \/\/ Handle success or failure\n    }\n}\n<\/code><\/pre>\n\n\n\n
    Reward Triggering<\/h2>\n\n\n\n
    Rewards are typically triggered on the server side, not the client side, to prevent manipulation. The flow:<\/p>\n\n\n\n
      \n
    1. The new user's app sends the referral code and the new user ID to your backend.<\/li>\n
    2. Your backend looks up the referrer by referral code.<\/li>\n
    3. Your backend records the referral (referrer user ID + referred user ID + timestamp + status: pending).<\/li>\n
    4. A webhook or background job fires when the referred user completes the required action (email verification, first purchase, subscription start).<\/li>\n
    5. The reward is granted to the referrer and optionally the referred user.<\/li>\n<\/ol>\n\n\n\n
      Separate the attribution step (recording the referral) from the reward step (granting the reward). This separation lets you:<\/p>\n\n\n\n