How Kalo Uses Flinku for Referral Deep Linking on iOS

Kalo is an AI-powered calorie tracking app for iOS. Users log meals by snapping a photo, speaking, or typing. The app includes a calorie ring dashboard, water tracking, a fasting tracker with Live Activities, a social accountability feature called Track, and an AI coach. It is available on the App Store at drkalo.app.

This post covers how Kalo uses Flinku's built-in referral attribution (SDK 0.6.0) so invite credit survives an App Store install, without DIY tracking.

The Problem: Referral Context Gets Lost at the App Store

Kalo has a referral program. When an influencer or existing user shares a referral link, the goal is simple: the person who taps that link should be recognized as a referral and the referrer should get credit.

The problem is the App Store. When a new user taps a referral link and does not have the app installed, they get redirected to the App Store. After installing and opening the app, the original link context is gone. The app has no way to know who referred them or what the original link contained.

This is deferred referral attribution. The referrer identity needs to survive the App Store install and be recovered when the new user signs up.

How Flinku Solves It (SDK 0.6.0)

Do not build this yourself by reading a ref param after match() and posting to your own backend. Flinku's referral system handles attribution automatically.

1. Create the invite link with referrer params

Each invite link includes referrerId (required for attribution) and optional referrerLabel (shown in the Flinku dashboard):

var options = FlinkuLinkOptions(title: "Invite from Sarah")
options.deepLink = "kalo://home"
options.params = [
  "referrerId": "user_sarah",
  "referrerLabel": "Sarah"
]

Flinku.createLink(options) { result in
  if case .success(let link) = result {
    // Share link.shortUrl, e.g. https://go.drkalo.app/invite-sarah
  }
}

createLinkInstant can also generate the short URL on-device with no network wait when the user taps Share.

2. Configure with a publishable key

Referral tracking requires the publishable key (flk_pk_...) in the app. Never embed the secret key (flk_live_).

Flinku.configure(
  baseUrl: "https://go.drkalo.app",
  apiKey: "flk_pk_..."
)

Without apiKey, setUserId and qualifyReferral silently do nothing.

3. Match deferred deep links on launch

On cold start, call Flinku.match() as usual so navigation still works after install. Matching also stores pending referral attribution for later.

Flinku.match { link in
  guard let link = link else { return }
  AppState.shared.pendingDeepLink = link
}

4. Call setUserId after signup or login

Once the new user completes sign in, call setUserId. The SDK attributes the referral automatically. You never call POST /api/referrals/track from the app.

// After signup or login
Flinku.setUserId(user.id)

5. Qualify when they do the rewarded action

Rewarding on install alone is easy to game. When the referred user logs their first meal (or whatever you actually reward), call qualifyReferral:

Flinku.qualifyReferral("first_meal")

Flinku can POST to your referralWebhookUrl when a referral qualifies. Credit coins or unlock a perk in your own system from that webhook. Authenticate the webhook endpoint.

The Custom Domain

Kalo uses a custom domain through Flinku: go.drkalo.app. All referral links use this domain instead of the default Flinku subdomain. This is available on the Growth and Studio plans and requires adding a CNAME record pointing to flku.dev and verifying it through the Flinku dashboard.

Every referral link looks like a native Kalo link with no trace of a third-party service. SDK baseUrl still uses the Flinku project host the dashboard gives you.

The Full Flow

Sarah shares an invite link created with referrerId=user_sarah. A follower taps it. They do not have Kalo installed. Flinku records their device fingerprint and redirects them to the App Store. They install Kalo and open it for the first time. Flinku.match() recovers the deep link for navigation. After sign in, Flinku.setUserId attributes the referral to Sarah. When they log their first meal, Flinku.qualifyReferral("first_meal") marks the referral qualified.

No manual ref parsing. No DIY track API. The attribution survives the entire App Store install flow.

Why This Matters for Referral Programs

Referral programs without deferred attribution only work when the app is already installed. Any new user who comes through the App Store loses the referral context. The referrer does not get credit, the new user does not get their referral benefit, and the incentive to share breaks down.

Flinku's 0.6.0 referral system fixes this: deferred match recovers the invite, setUserId attributes it, and qualifyReferral rewards the real action.

Getting Started

Flinku is available at flinku.dev. The iOS SDK is on GitHub (flinku-dev/ios-sdk, version 0.7.0). The free plan includes deferred deep linking and referrals with no credit card required.

Full referral docs: docs.flinku.dev/docs/referral-system.