Links for every item

Referrals and parameters

Carry a referral code or campaign through open, install and your website.

A shared link often carries something about who shared it: a referral code, a campaign, a source. Item links keep that separate from the item itself, so one item has one card and one cache entry, while every click keeps its own parameters.

The rule#

The item is the id in the path: /c/4521.
The context is the query: ?ref=U7K2X9AB&utm_source=story.

Both reach your app, the context only when the template has Pass query parameters on.

Where the parameters go#

Moment	What your code sees
App installed, link opened	`LinkEvent.params` holds every query parameter of the opened URL
App installed after the click (deferred)	`LinkEvent.params` holds the parameters stored with the click, if the template allows pass-through (at most 4 KB, last value wins)
Your website (desktop visitors, no app)	The `{query}` placeholder at the end of the template's `web`, `desktop` or `fallback` URL appends them. Without it your site never sees the query
The link preview in a chat app	Never. The card and its `og:url` are the same for every referral

Dart

BeckLink.instance.onLink.listen((link) {
  final item = link.resource;         // LinkResource(type: 'challenge', id: '4521')
  final ref = link.params['ref'];     // 'U7K2X9AB', or null
  if (item == null) return;
  openChallenge(item.id, referral: ref); // load through your API and validate on your server
});

What Beck Links does not do#

Beck Links passes ref through unchanged. It cannot tell whether a code is genuine. Anyone can edit a URL. Validate the code on your own server before you reward anyone:

Does the code exist and belong to an eligible user?
Does it match the item (for example the right campaign)?
Is the user the sharer (no self-referral)?
Reward once per referred user, not once per click or open: the same link is opened many times.

Prefer opaque or signed codes. A referral can be personal data in your policy: it is stored with the click and in the install's deferred payload only when the template passes parameters through, and it is never sent to your metadata endpoint, put in a cache key, a card or a log.

Do not create a link per user#

A link string is free to build (https://acme.becklinks.com/c/{id}?ref={code}), so build it where you need it. Creating a Beck Links link for every user or item is what item patterns exist to avoid.

Verify it works#

Open …/c/4521?ref=A and …/c/4521?ref=B on a test phone with the app: your listener receives the same resource and a different ref.
As a crawler (curl -A 'facebookexternalhit/1.1' …) both give the same card.
Count referrals in your own system from what the app reports after validation. Beck Links keeps the parameters with each click, but its dashboard counts per template and item; it does not break results down by referral code.