{"id":1897,"date":"2026-07-31T09:00:00","date_gmt":"2026-07-31T14:00:00","guid":{"rendered":"https:\/\/tolinku.com\/blog\/?p=1897"},"modified":"2026-03-07T03:50:18","modified_gmt":"2026-03-07T08:50:18","slug":"cross-platform-referral-links","status":"publish","type":"post","link":"https:\/\/tolinku.com\/blog\/cross-platform-referral-links\/","title":{"rendered":"Cross-Platform Referral Links That Work Everywhere"},"content":{"rendered":"\n

A referral link should work the same whether the recipient is on iOS, Android, or web. Tap the link, see the referral content, and attribute the referral to the sender. In practice, each platform handles URLs differently, and the recipient might not have the app installed. This article covers how to build referral links that handle all these cases.<\/p>\n\n\n\n

For referral deep link mechanics, see how referral deep links work: end-to-end guide<\/a>. For building effective referral programs, see building referral programs that actually work<\/a>.<\/p>\n\n\n\n

The Problem<\/h2>\n\n\n\n

A referral link like https:\/\/yourdomain.com\/referral\/user123<\/code> needs to:<\/p>\n\n\n\n

    \n
  1. Open the native app if installed (iOS or Android).<\/li>\n
  2. Navigate to the correct screen with the referrer's ID.<\/li>\n
  3. If the app is not installed, take the user to the app store or a landing page.<\/li>\n
  4. After installation, still attribute the referral to user123<\/code>.<\/li>\n<\/ol>\n\n\n\n

    Each requirement has platform-specific challenges:<\/p>\n\n\n\n

    \n\n\n\n\n\n\n
    Requirement<\/th>\niOS<\/th>\nAndroid<\/th>\nWeb<\/th>\n<\/tr>\n<\/thead>\n
    Open app<\/td>\nUniversal Links<\/td>\nApp Links<\/td>\nN\/A<\/td>\n<\/tr>\n
    Navigate to screen<\/td>\nAppDelegate\/SceneDelegate<\/td>\nIntent<\/td>\nURL routing<\/td>\n<\/tr>\n
    App not installed<\/td>\nFallback to App Store<\/td>\nFallback to Play Store<\/td>\nShow landing page<\/td>\n<\/tr>\n
    Post-install attribution<\/td>\nDeferred deep link<\/td>\nDeferred deep link<\/td>\nCookie\/localStorage<\/td>\n<\/tr>\n<\/tbody><\/table><\/figure>\n\n\n\n

    Referral Link Structure<\/h2>\n\n\n\n

    Use a consistent URL format that works across platforms:<\/p>\n\n\n\n

    https:\/\/yourdomain.com\/referral\/{referrerId}?campaign={campaignId}\n<\/code><\/pre>\n\n\n\n
    The URL is the same for all platforms. Platform detection happens server-side or client-side when the link is opened.<\/p>\n\n\n\n
    Server-Side Detection<\/h3>\n\n\n\n
    When the URL is opened in a browser (app not installed), detect the platform and redirect:<\/p>\n\n\n\n
    \/\/ Server route handler\napp.get('\/referral\/:referrerId', (req, res) => {\n  const { referrerId } = req.params;\n  const userAgent = req.headers['user-agent'] || '';\n\n  \/\/ If the app handles this via Universal Links \/ App Links,\n  \/\/ this handler won't be called. This runs only when the app\n  \/\/ isn't installed or links aren't verified.\n\n  if (\/iPhone|iPad|iPod\/.test(userAgent)) {\n    \/\/ iOS: redirect to App Store with context\n    res.redirect(\n      `https:\/\/apps.apple.com\/app\/id${APP_STORE_ID}?referrer=${referrerId}`\n    );\n  } else if (\/Android\/.test(userAgent)) {\n    \/\/ Android: redirect to Play Store with referrer\n    res.redirect(\n      `https:\/\/play.google.com\/store\/apps\/details?id=${PACKAGE_NAME}&referrer=${referrerId}`\n    );\n  } else {\n    \/\/ Web: show referral landing page\n    res.render('referral-landing', { referrerId });\n  }\n});\n<\/code><\/pre>\n\n\n\n
    Native App Handling<\/h2>\n\n\n\n
    iOS<\/h3>\n\n\n\n
    Configure Universal Links so https:\/\/yourdomain.com\/referral\/*<\/code> opens the app:<\/p>\n\n\n\n
    AASA file:<\/p>\n\n\n\n
    {\n  "applinks": {\n    "details": [{\n      "appIDs": ["TEAMID.com.yourcompany.yourapp"],\n      "components": [\n        { "\/": "\/referral\/*" }\n      ]\n    }]\n  }\n}\n<\/code><\/pre>\n\n\n\n
    Handle in the app:<\/p>\n\n\n\n
    func application(_ application: UIApplication,\n                 continue userActivity: NSUserActivity,\n                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {\n    guard let url = userActivity.webPageUrl,\n          let components = URLComponents(url: url, resolvingAgainstBaseURL: false) else {\n        return false\n    }\n\n    let path = components.path\n    if path.hasPrefix("\/referral\/") {\n        let referrerId = String(path.dropFirst("\/referral\/".count))\n        handleReferral(referrerId: referrerId)\n        return true\n    }\n\n    return false\n}\n\nfunc handleReferral(referrerId: String) {\n    \/\/ Store the referral\n    UserDefaults.standard.set(referrerId, forKey: "pending_referrer")\n\n    \/\/ Navigate to referral welcome screen\n    let vc = ReferralWelcomeViewController(referrerId: referrerId)\n    rootNavigationController?.pushViewController(vc, animated: true)\n}\n<\/code><\/pre>\n\n\n\n
    Android<\/h3>\n\n\n\n
    Intent filter:<\/p>\n\n\n\n
    <intent-filter android:autoVerify="true">\n    <action android:name="android.intent.action.VIEW" \/>\n    <category android:name="android.intent.category.DEFAULT" \/>\n    <category android:name="android.intent.category.BROWSABLE" \/>\n    <data android:scheme="https"\n          android:host="yourdomain.com"\n          android:pathPrefix="\/referral" \/>\n<\/intent-filter>\n<\/code><\/pre>\n\n\n\n
    Handle in the activity:<\/p>\n\n\n\n
    override fun onCreate(savedInstanceState: Bundle?) {\n    super.onCreate(savedInstanceState)\n    handleReferralIntent(intent)\n}\n\noverride fun onNewIntent(intent: Intent) {\n    super.onNewIntent(intent)\n    handleReferralIntent(intent)\n}\n\nprivate fun handleReferralIntent(intent: Intent) {\n    val uri = intent.data ?: return\n    if (uri.path?.startsWith("\/referral\/") == true) {\n        val referrerId = uri.lastPathSegment ?: return\n        handleReferral(referrerId)\n    }\n}\n\nprivate fun handleReferral(referrerId: String) {\n    \/\/ Store the referral\n    getSharedPreferences("referral", MODE_PRIVATE)\n        .edit()\n        .putString("pending_referrer", referrerId)\n        .apply()\n\n    \/\/ Navigate to referral screen\n    val intent = Intent(this, ReferralWelcomeActivity::class.java).apply {\n        putExtra("referrer_id", referrerId)\n    }\n    startActivity(intent)\n}\n<\/code><\/pre>\n\n\n\n
    Deferred Deep Linking<\/h2>\n\n\n\n
    The hardest case: the user taps the referral link but does not have the app installed. After they install and open the app, the referral should still be attributed.<\/p>\n\n\n\n
    How Deferred Deep Links Work<\/h3>\n\n\n\n
      \n
    1. User taps https:\/\/yourdomain.com\/referral\/user123<\/code>.<\/li>\n
    2. App not installed; user lands on a web page or app store.<\/li>\n
    3. The referral context (referrer ID, timestamp, campaign) is stored server-side, associated with a fingerprint (IP, device info, timestamp).<\/li>\n
    4. User installs the app and opens it.<\/li>\n
    5. On first launch, the app calls a server endpoint with its fingerprint.<\/li>\n
    6. Server matches the fingerprint and returns the original referral context.<\/li>\n
    7. App processes the referral.<\/li>\n<\/ol>\n\n\n\n
      Server-Side Fingerprint Storage<\/h3>\n\n\n\n
      \/\/ When the referral link is opened in a browser\napp.get('\/referral\/:referrerId', async (req, res) => {\n  const { referrerId } = req.params;\n\n  \/\/ Store fingerprint for deferred matching\n  const fingerprint = {\n    ip: req.ip,\n    userAgent: req.headers['user-agent'],\n    timestamp: Date.now(),\n    referrerId,\n    campaign: req.query.campaign\n  };\n\n  await storeDeferredLink(fingerprint);\n\n  \/\/ Redirect to app store or landing page\n  redirectByPlatform(req, res, referrerId);\n});\n\n\/\/ When the app calls on first launch\napp.post('\/api\/deferred-link', async (req, res) => {\n  const { ip, userAgent, deviceId } = req.body;\n\n  const match = await findDeferredLink({\n    ip,\n    userAgent,\n    maxAge: 48 * 60 * 60 * 1000 \/\/ 48 hours\n  });\n\n  if (match) {\n    res.json({\n      found: true,\n      referrerId: match.referrerId,\n      campaign: match.campaign\n    });\n    \/\/ Mark as consumed\n    await markDeferredLinkUsed(match.id);\n  } else {\n    res.json({ found: false });\n  }\n});\n<\/code><\/pre>\n\n\n\n
      Client-Side (First Launch)<\/h3>\n\n\n\n
      \/\/ iOS: check for deferred link on first launch\nfunc checkDeferredLink() {\n    guard !UserDefaults.standard.bool(forKey: "deferred_link_checked") else {\n        return\n    }\n\n    UserDefaults.standard.set(true, forKey: "deferred_link_checked")\n\n    let body: [String: Any] = [\n        "deviceId": UIDevice.current.identifierForVendor?.uuidString ?? "",\n        "userAgent": "iOS\/\\(UIDevice.current.systemVersion)"\n    ]\n\n    \/\/ POST to your server\n    apiClient.post("\/api\/deferred-link", body: body) { result in\n        if let referrerId = result.referrerId {\n            self.handleReferral(referrerId: referrerId)\n        }\n    }\n}\n<\/code><\/pre>\n\n\n\n
      Attribution Consistency<\/h2>\n\n\n\n
      Referral attribution must be consistent regardless of how the user arrived. Track the referral source for analytics:<\/p>\n\n\n\n
      interface ReferralAttribution {\n  referrerId: string;\n  platform: 'ios' | 'android' | 'web';\n  method: 'direct' | 'deferred';   \/\/ Direct = app was installed; Deferred = installed after\n  campaign?: string;\n  timestamp: number;\n}\n\nfunction attributeReferral(attribution: ReferralAttribution) {\n  \/\/ Store locally\n  localStorage.setItem('referral', JSON.stringify(attribution));\n\n  \/\/ Send to server\n  api.post('\/api\/referral\/attribute', attribution);\n}\n<\/code><\/pre>\n\n\n\n
      Preventing Double Attribution<\/h3>\n\n\n\n
      A referral should only be attributed once. Guard against duplicate attributions:<\/p>\n\n\n\n
      async function processReferral(referrerId: string, method: string) {\n  \/\/ Check if already attributed\n  const existing = await getReferralAttribution(userId);\n  if (existing) {\n    console.log('Referral already attributed:', existing.referrerId);\n    return;\n  }\n\n  \/\/ Store attribution\n  await storeReferralAttribution({\n    userId,\n    referrerId,\n    method,\n    timestamp: Date.now()\n  });\n\n  \/\/ Credit the referrer\n  await creditReferrer(referrerId);\n}\n<\/code><\/pre>\n\n\n\n
      Landing Pages for Web Users<\/h2>\n\n\n\n
      When a desktop user clicks a referral link, they cannot install a mobile app. Show a landing page that:<\/p>\n\n\n\n
        \n
      1. Explains the referral offer.<\/li>\n
      2. Provides app store links (with referral context).<\/li>\n
      3. Allows web signup (if applicable).<\/li>\n<\/ol>\n\n\n\n
        <!-- referral-landing.html -->\n<div class="referral-page">\n  <h1>You've been invited!<\/h1>\n  <p>Your friend shared something with you.<\/p>\n\n  <div class="app-links">\n    <a href="https:\/\/apps.apple.com\/app\/idYOUR_ID"\n       class="app-store-badge">\n      Download on the App Store\n    <\/a>\n    <a href="https:\/\/play.google.com\/store\/apps\/details?id=com.yourapp"\n       class="play-store-badge">\n      Get it on Google Play\n    <\/a>\n  <\/div>\n\n  <p>Or <a href="\/signup?ref=USER123">sign up on the web<\/a><\/p>\n<\/div>\n<\/code><\/pre>\n\n\n\n
        Testing Referral Links<\/h2>\n\n\n\n
        Direct Attribution (App Installed)<\/h3>\n\n\n\n
        # iOS\nxcrun simctl openurl booted "https:\/\/yourdomain.com\/referral\/user123?campaign=summer"\n\n# Android\nadb shell am start -a android.intent.action.VIEW \\\n  -d "https:\/\/yourdomain.com\/referral\/user123?campaign=summer" \\\n  -c android.intent.category.BROWSABLE\n<\/code><\/pre>\n\n\n\n
        Verify:<\/p>\n\n\n\n