Track referrals

Pass a referral code through install, read it in your app, and record the referral

Before you start

For

App developers

Time

About 1 hour

You need

• Your link domain set up (see Use your own link domain)
• Deep links set up in your app (see Set up deep links)
• A backend that creates, checks and rewards referral codes

Linkrunner carries a referral code from a clicked link through install. Your app reads the code from the deeplink returned by getAttributionData() and sends it to your backend.

Your app is responsible for creating referral codes, validating them, and applying rewards.

Watch the one-minute walkthrough with sound on, or follow the steps below.

Before you start

• Set up your link domain: a Linkrunner sub-domain, or a Branded sub-domain such as get.example.com.
• Set up deep linking for your app.
• Use referrer as the query parameter name. Linkrunner reports links that carry it under the Referrals channel.

1. Create a referral link

Add the referring user's code or ID to your Linkrunner subdomain:

https://get.example.com?referrer=user_123

You can include an app destination in the same link:

https://get.example.com/product/987?referrer=user_123

Generate the link in your app or backend when a user opens your referral or invite screen. URL-encode the value before adding it to the link.

You do not need to create a campaign to pass a referral code. Clicks and installs from these links appear in the Referrals row of the Channels table.

2. Share the link

Let the referring user share the complete link. Keep the referrer parameter intact through any redirect or URL shortener.

When the recipient opens the link, Linkrunner sends them to the app or store. After install, the original URL is available in getAttributionData():

{
  "deeplink": "https://get.example.com?referrer=user_123"
}

3. Read the referral code

Call getAttributionData() after the Linkrunner SDK is initialized. Parse the returned deeplink and read the referrer query parameter.

val referralCode = attributionData.deeplink
    ?.let { Uri.parse(it).getQueryParameter("referrer") }

Get attribution data on Android

let referralCode = URLComponents(string: deeplink)?
    .queryItems?
    .first(where: { $0.name == "referrer" })?
    .value

Get attribution data on iOS

const referralCode = new URL(attributionData.deeplink)
  .searchParams.get("referrer");

Get attribution data in React Native

final referralCode = Uri.parse(attributionData.deeplink!)
    .queryParameters['referrer'];

Get attribution data in Flutter

Store the code until the recipient signs up or completes the event that qualifies the referral.

4. Record the referral

Send the referral code and the recipient's user ID to your backend. Validate the relationship and record it before applying a reward.

At a minimum, reject:

• Invalid or expired codes
• Self-referrals
• A recipient using more than one referral code
• The same qualifying event being rewarded twice

Validate referrals and grant rewards on your backend. Do not trust a referral code submitted only by the client.

See referral results

Open App Campaigns → Channels in the dashboard. Clicks, installs, sign-ups, and revenue from referral links appear in the Referrals row.

A click counts as a referral when it uses your subdomain without a campaign and carries a referral code in referrer. Linkrunner also accepts AppsFlyer's af_referrer_customer_id and af_referrer_uid. The value must be a plain code, such as user_123.

To report a referral program as its own campaign instead, append the referral parameter to a generated campaign link:

https://get.example.com/AbCdEf?referrer=user_123

These clicks and installs appear under that campaign's channel, not under Referrals. See Deep Link Management for the campaign setup and parameter precedence rules.

Testing

1. Create a referral link with a test code.
2. Uninstall the app from a real device.
3. Open the referral link, then install and open the app.
4. Confirm that getAttributionData() returns the link in deeplink.
5. Confirm that your app extracts the referral code.
6. Sign up and confirm that your backend records the correct referrer and recipient.

Deferred attribution is stored from the first install. Uninstall the app before repeating a test with a different referral code.

Troubleshooting

deeplink is null. Confirm that the SDK was initialized before calling getAttributionData() and that the app was installed through the referral link.

The referral parameter is missing. Open the final URL before the store redirect and confirm that no redirect or URL shortener removed it.

The previous referral code is returned. Uninstall the app before testing another link. Attribution data is cached from the first install.

The referral is not in the Referrals row. Confirm that the link uses your subdomain without a campaign and that the referrer value is a plain code. Referral links inside a campaign appear under that campaign's channel. Clicks from before the Referrals channel was released stay under Linkrunner Links.

The code is present but no referral is recorded. Check the app-to-backend request and your referral validation logic. Linkrunner forwards the code but does not apply referral rules or rewards.

Need help? Contact support@linkrunner.io