Referral widget

Basic setup

In cloud mode the referral code, the link and the reward copy all come from your dashboard, so the widget takes no props at all.

import { ReferralWidget } from "@roastnest/react";

function InvitePage() {
  return <ReferralWidget />;
}

In self-hosted mode you supply the link and the event handler, and the SDK generates and persists the referral code in localStorage.

import { ReferralWidget } from "@roastnest/react";

function InvitePage() {
  return (
    <ReferralWidget
      mode="self-hosted"
      referralLink="https://myapp.com/invite"
      appName="My Awesome App"
      referrerRewardType="monetary"
      referrerRewardAmount="$20"
      refereeRewardType="monetary"
      refereeRewardAmount="$10"
      onEvent={(payload) => console.log("Referral event:", payload)}
    />
  );
}

How links are generated

Self-hosted mode generates a unique code per user on first mount and stores it under roastnest_my_referral_code. It is appended to the link you provide as a query parameter — give it https://myapp.com/invite and users share https://myapp.com/invite?ref=AYUSH123.

Cloud mode fetches both the code and the finished link from the server on mount, so the same user gets the same link across devices.

On the receiving end, the SDK detects the parameter on arrival and persists it, so a visitor who lands on your marketing page and signs up three pages later is still attributed. See Conversion tracking.

Content props

Trigger and popup

Sharing and copying

The card offers a copy-to-clipboard action and, where the browser supports the Web Share API, a native share sheet.

Referrer identity

To tie a referral link to a known user rather than an anonymous visitor, pass referrerIdentity. Nothing to compute and no secret to manage — pass the user you already have.

<ReferralWidget
  referrerIdentity={{
    id: user.id,        // your own user id
    name: user.name,
    email: user.email,
  }}
/>

Identifying without an email

If you would rather not send us your users' email addresses, don't. Send your own user id and nothing else — we keep a stable person for it, so the same user gets the same referral code on every visit, and every webhook about them carries that id straight back to you.

// No email leaves your system.
<ReferralWidget
  referrerIdentity={{
    id: user.id,
    name: user.name,
  }}
/>

The reverse works too, for cases where you have no stable id to hand:

// No stable id to hand us? Email alone works.
<ReferralWidget
  referrerIdentity={{
    email: user.email,
    name: user.name,
  }}
/>

Callbacks

Custom rendering

If the stock card does not fit, replace either half of it. renderTrigger swaps the floating button and renderCard swaps the card body, both receiving the state and actions they need as arguments. customCSS injects a stylesheet scoped to the widget for smaller adjustments.

<ReferralWidget
  renderTrigger={({ open, isOpen }) => (
    <button onClick={open} disabled={isOpen}>
      Invite a friend
    </button>
  )}
/>

Lifecycle visualizer

ReferralLifecycle renders a stage-by-stage view of the referral flow — shared, clicked, saved, action, attributed, reward approved — and lets you step through it without running real traffic. It is a development aid; leave it out of production builds.

import { ReferralLifecycle } from "@roastnest/react";

function DebugPanel() {
  return <ReferralLifecycle />;
}