Skip to main content

Referral Links That Credit the Right Person

A referral program pays one user for bringing in another. The hard parts are knowing who to credit once the new user has been through the app store, and knowing when to say no.

This guide describes a design for both. It records the referral on a server, pays from a webhook (a signed request the link service sends to your backend), and lets the app show results without deciding them. The examples use AdTo's Flutter SDK and webhooks.

Where the inviter gets lost

The journey has five steps: the friend taps the invite link, lands in the store, installs, opens the app, and signs up. The link is tapped at the first step, but the app first runs at the fourth, after the store, so something has to carry the invite across.

Carrying the tap across the store is called deferred deep linking. The link service records the tap, and the SDK reports the first launch so the server can match the two. In AdTo the store redirect carries a click id. On Android the SDK reads it back from the Play Install Referrer, the Google Play API that returns an install's referral content. On iOS, when the app has tap-to-store turned on, the tap-to-store page copies the link to the pasteboard (the system clipboard) and the SDK reads it at first launch. When neither signal is there, the server falls back to a fingerprint: a scored comparison of the tap and the first launch, starting from a hashed IP address.

The inviter can drop out at three points:

  • The install is not matched to the tap. It counts as organic, meaning no link is credited, and names nobody.
  • The match is not sure enough. AdTo credits an install only at a matchConfidence of guaranteed or high. A medium fingerprint match can still route the new user to the right screen, but it credits no one.
  • The signup does not qualify. It never happens, it comes too late, or the person was not a new user (covered below).

Two link designs

A link per customer

Each user gets a link of their own, tied to their customer id on the server.

final link = await adto.createReferralLink(customerId: currentUser.id);
share(link.url); // e.g. https://acme.adto.app/r-3fa94c1b2e

createReferralLink creates the link on the first call and returns the same link afterwards. It works with the app's ordinary SDK key, which cannot create other links. customerId is the id you pass to identify. A backend can make the same link with POST /api/v1/referral-links.

One link with the referrer in the URL

If your backend already builds share links, keep one permanent link and add the sharer's id as adto_referrer:

https://acme.adto.app/invite?adto_referrer=1042&adto_label=spring

The install, the referral record and the webhook work the same way. What differs is who decides the referrer.

A link per customerOne link with adto_referrer
Where the referrer is setOn the server, from the linkIn the tapped URL
Can someone change itNo. Parameters added to the link do not change itYes. Anyone can edit the URL to name another customer
What you addOne SDK or API call per userA query parameter on a link you already share

If the reward is worth money, use a link per customer. If you choose the URL parameter, your reward code has to check that the id it receives belongs to a real user of yours.

When the referral is recorded

A tap is not a referral, and neither is an install, which has no account to credit. The referral is recorded at signup, when your code tells the SDK who the new user is:

await adto.identify(customerId: user.id);

The server records a referral when that call is the first identify of a new customer, on an install that is at most 30 days old, that is not a reinstall or an app update, and that was credited to a referral link or to a tap carrying adto_referrer. An install records at most one referral.

The record holds referrer_customer_id, referee_customer_id, the install and the link, how the install was matched (match_source, match_confidence), a fraud_flags list and a status of converted or rejected. The server makes it from the link the install was credited to, so a modified app cannot claim someone else's reward.

Pay from a server webhook, not from the app

The app is the wrong place to grant a reward, because a modified app can show anything. Let the app report the signup and let your server pay.

AdTo sends a referral.converted webhook to your backend when a referred user signs up:

{
  "event_id": "evt_1f0c…",
  "event": "referral.converted",
  "created_at": "2026-10-14T13:20:11.000Z",
  "attempt": 1,
  "data": {
    "username": "acme",
    "referral": {
      "id": "8b1d…",
      "referrer_customer_id": "u_1042",
      "referee_customer_id": "u_2210",
      "install_id": "3d2b6c1e-…",
      "match_source": "referrer",
      "match_confidence": "guaranteed",
      "fraud_flags": [],
      "created_at": "2026-10-14T13:20:11.000Z",
      "link": { "slug": "r-3fa94c1b2e", "url": "https://acme.adto.app/r-3fa94c1b2e" }
    },
    "processed_at": "2026-10-14T13:20:11.000Z"
  }
}

A handler that pays correctly does six things:

  1. Verify the signature. x-adto-signature is sha256= followed by the HMAC-SHA256 of the raw request body, keyed with the webhook's secret. Check it against the bytes as received, before parsing the JSON.
  2. Answer 2xx quickly and do the work afterwards. No answer within 10 seconds counts as a failure, and deliveries are not ordered.
  3. Deduplicate on event_id. A failed delivery is retried for about a day, and every attempt and manual resend carries the same id.
  4. Key the reward on referral.id so one referral pays once.
  5. Look both customers up in your own database. With adto_referrer the referrer id is whatever the URL said.
  6. Apply your policy to fraud_flags and match_confidence. Rewarding only guaranteed matches is a decision to make here.

When to refuse, and when to review

Never recorded

The server records no referral, and sends no referral.converted, when:

  • the device had the app before (a reinstall);
  • the user already had the app and updated to a build that includes the SDK (an app update);
  • the customer existed before the install, such as an existing user signing in on a new phone;
  • the link named the customer themself (a self-referral);
  • the signup came more than 30 days after the install;
  • another customer already signed up on the same install, since an install credits one referral;
  • a fraud rule your app blocks withheld the install's credit.

The reinstall is the usual one in testing. On iOS the SDK keeps its device id in the Keychain to recognise a device that had the app before, so a test phone that had it reports a reinstall.

Recorded and flagged

Every referral is checked against two fraud rules of its own. The referral is recorded either way. Unless you block the rule (see below), the webhook still fires and fraud_flags names what hit.

FlagStrengthFires whenSuggested policy
referral_same_deviceStrongThe new customer signed up on a device the referrer used. The usual case is someone installing through their own link, then making a second account.Refuse
referral_same_networkWeakThe install came from a network one of the referrer's other devices used in the 30 days before. Never on cellular data.Review. A household trips it too

The list also carries the install's own flags, such as emulator or signing_cert_mismatch for a re-signed build.

Rejected for you

If you would rather not write that policy, tick Reject referral for either rule under Fraud rules on the dashboard's Apps page. A referral that trips it is stored as rejected, sends no referral.converted and is not counted, so your reward code never sees it.

These rules catch abuse through the real SDK. The SDK key ships inside your app, so the rules do not prove that a request came from a genuine device, and device attestation is not part of AdTo yet. Keep a ceiling on what one account can earn.

Show who invited them, and explain a missing credit

The install result names the referrer, enough for an "Invited by" screen:

final install = await adto.getAttributionData();
final referrer = install?.link?.referrerCustomerId; // "u_1042", or null
if (referrer != null && !install!.isReinstall) {
  showInvitedBy(referrer); // look the name up in your own backend
}

referrerCustomerId is set only on a credited install. A reinstall never records a referral, so check isReinstall before the screen promises anything. Use the value for display only.

No webhook announces a refusal, so the explanation comes from two places. For support, the customer's page in the dashboard shows the referrer under Referred by with a not credited chip and the reason, or a rejected chip with the flags. For the app, your backend knows whether a webhook arrived and what it decided. A workable pattern:

  • Show the inviter a pending state until your server has processed the webhook.
  • Publish the rules next to the invite button: new users only, one reward per person, signup within 30 days of installing.
  • When the answer is no, give the plain reason, for example "This invite did not count because the app was installed on this phone before." The app knows a reinstall from isReinstall, and your backend knows an existing account or a self-invite from its own user table.
  • For a flagged referral, say it is under review. Do not name the rule that fired.

A short checklist

  • One link per customer when the reward has value.
  • identify called at signup, with the id your backend uses.
  • A webhook subscribed to referral.converted, with the signature verified on the raw body.
  • Deduplication on event_id and one reward per referral.id.
  • A written policy for each fraud flag and for match_confidence.
  • isReinstall checked before the app shows a reward.
  • A pending state in the UI and a plain reason for every refusal.
  • A test on a device that never had the app.

Doing this with AdTo

AdTo is a hosted service for short deep links, deferred deep links and install attribution, and its links live at https://<username>.adto.app/<slug>. For a referral program it supplies the three pieces this guide relies on: a referral link per customer from one call in the flutter_adto SDK, a referral record made on the server at the new user's first identify, and a signed referral.converted webhook that carries the fraud flags.

In the dashboard, referral links have their own tab with clicks, installs, referrals and the number flagged or rejected. Each customer's page shows who referred them, or why nobody was credited.

AdTo is not a measurement partner (MMP) and sends no postbacks to ad networks. It covers the link, the match and the record. The reward stays in your backend.

Create an AdTo account, then follow the referral programs guide step by step. For the wider picture on abuse, read Referral and install fraud for small apps.