Headless SDK: referrals
useReferral returns the participant's code, share URL, pre-filled message, and history. Pre-fill is the single most under-implemented detail; the hook makes it free.
Key takeaways
Quick read- useReferral returns code, shareUrl, defaultMessage, and history.
- Always pre-fill the share message. Asking the user to write loses 50 percent of share intent.
- Use share() for native share sheet on mobile and copy-to-clipboard on desktop.
- Show history compactly. Pending and converted states matter; raw click counts do not.
- Tier-based reward bumps (more for the 5th referral) are configured server-side; the hook reflects them.
Render referrals
Code, share, and history
"use client";
import { useReferral } from "@bricqs/headless-react";
export function ReferralPanel() {
const { code, shareUrl, defaultMessage, history, share, isLoading } =
useReferral();
if (isLoading) return null;
async function onShare() {
const ok = await share({ message: defaultMessage });
if (ok) trackAnalytics("referral_shared");
}
return (
<section className="rounded-xl border p-5">
<header className="mb-3">
<h3 className="font-bold">Invite a friend</h3>
<p className="text-sm text-slate-500">
Give 200 INR off, get 200 INR off. They sign up with your link, you both earn.
</p>
</header>
<div className="flex items-center gap-2 mb-4">
<code className="px-3 py-2 rounded bg-slate-100 font-mono text-sm flex-1">
{code}
</code>
<button onClick={() => navigator.clipboard.writeText(shareUrl)} className="text-sm">
Copy link
</button>
<button onClick={onShare} className="px-4 py-2 rounded-lg bg-orange-500 text-white">
Share
</button>
</div>
<div>
<h4 className="font-semibold text-sm mb-2">Your invites</h4>
<ul className="grid gap-1 text-sm">
{history.map((h) => (
<li key={h.id} className="flex items-baseline justify-between">
<span>{h.invitedDisplayName ?? "Pending invite"}</span>
<span
className={
h.status === "converted"
? "text-green-600"
: "text-slate-400"
}
>
{h.status === "converted" ? `+${h.rewardLabel}` : h.status}
</span>
</li>
))}
</ul>
</div>
</section>
);
}The message
Pre-fill is mandatory
Default message format the SDK ships:
"Hey, I've been using {brand}. Sign up with my code {code}
and we both get 200 INR off."
You can override per-locale or per-cohort via the dashboard.
Always test on the channel: WhatsApp truncates at ~80 chars; SMS at ~160.
The shareUrl is appended automatically by share(); do not double-paste it.Common mistakes
What goes wrong
Asking the user to type the message themselves. 50 percent share-intent loss.
Pre-fill defaultMessage. Let users edit; most do not.
Sharing only the bare code (no URL). The friend has no way to apply it.
Use shareUrl which carries the code as a query param. Server-side attribution kicks in on signup.
Building click-based reward attribution. Bots inflate the count.
Bricqs reward attribution fires only on conversion (signup, qualifying purchase). Click counts are vanity.
Hiding the history. Users forget who they invited and lose motivation.
Show history with status. Converted invites are the proof the program is working.
Developer FAQ
Common questions when integrating gamification with Bricqs.
Ready to ship?
Wire it up with the Bricqs SDK or API
Headless SDK for React UIs, REST API for any backend. Same engine behind both.