Referral Widget
Embed the Referral Widget, sign its short-lived token on your backend, and configure its design in the Console.
The Referral Widget is a button and a panel that you add to your product. It shows a signed-in customer their referral link, a copy button, and share buttons. When the customer has cash Rewards that RefRef pays out, it also shows their payout amounts and collects their PayPal address.
The Widget shows link sharing only. It does not show a referral history or a Reward list.
How it works
- Your backend signs a short-lived Widget token for the signed-in customer and the referral Program with the Project's client secret.
- The page loads the Widget script and calls
window.RefRef.initwith the token. The page names no Project and no Program. - The Widget calls
POST /v1/widget/init. RefRef finds the customer named by the token, or creates it, and returns its link in the Program of the token.
Your signup call already enrolls a new customer in the referral Program and creates their code, unless you turned off "Enroll every new customer" in the Program settings. Otherwise, the first time the Widget opens for a customer, RefRef enrolls them. You do not enroll customers from your backend. If you end a customer's enrollment, the Widget does not enroll them again in that Program. Widget initialization never records an Event.
1. Sign the token on your backend
Get the Client secret in the Console: open the Project, then Developers → Secrets (owners and admins only). The Sandbox and Live Projects have different secrets. Keep the secret on your server. If it leaks, rotate it: the old secret stops working at once.
The token is a JWT with these rules:
| Part | Value |
|---|---|
| Algorithm and header | HS256, with typ: "refref-widget+jwt" |
sub | Your ID of the customer: the same externalId that your backend sends |
participantKind | individual or group |
programId | The ID of the referral Program that the Widget shows |
aud | refref-widget |
scope | widget:read widget:payout for the full Widget, or widget:read to view only |
iat, exp | At most 3 hours apart |
email (optional) | The customer's email address |
The token has no Project claim: the Program gives the Project. Sign the token with the secret of the Program's Project. widget:read lets the Widget show the link and the payout amounts. widget:payout also lets the customer save their payout details. RefRef keeps email as the customer's contact email and fills in the PayPal address of the payout form with it; the customer can change it. RefRef never sends the customer an email. RefRef drops other claims.
This Node.js example uses the jose library:
import { SignJWT } from "jose";
export async function widgetToken(userId: string) {
return new SignJWT({
programId: process.env.REFREF_PROGRAM_ID!,
participantKind: "individual",
scope: "widget:read widget:payout",
})
.setProtectedHeader({ alg: "HS256", typ: "refref-widget+jwt" })
.setAudience("refref-widget")
.setSubject(userId)
.setIssuedAt()
.setExpirationTime("15m")
.sign(new TextEncoder().encode(process.env.REFREF_CLIENT_SECRET!));
}Serve the token from an authenticated route of your app, for example GET /refref/widget-token. Sign a token only for the customer of the current session.
For a company account, sign the token with participantKind: "group" and the company's ID as sub. Every person to whom you give that token sees the company's link.
With several referral Programs, your backend decides which Program each customer sees: put that Program's ID in the customer's token. The first time the Widget loads with a Program, RefRef enrolls the customer in it.
2. Load the Widget
<script src="https://assets.refref.ai/widget.v1.js" defer></script>
<script>
const getToken = () =>
fetch("/refref/widget-token").then((response) => response.text());
window.RefRef = window.RefRef || [];
getToken().then((token) =>
window.RefRef.push([
"init",
{
apiUrl: "https://api.refref.ai",
token,
getToken,
},
]),
);
</script>The array form queues the call until the script loads. After the script loads, you can also call window.RefRef.init({ ... }) directly; it returns a promise.
| Option | Required | Meaning |
|---|---|---|
token | Yes | The signed Widget token. It names the Program and the customer. |
getToken | No | A function that returns a new token. On a 401 answer, the Widget calls it once and tries again. |
apiUrl | No | The RefRef API, https://api.refref.ai |
demo | No | true shows example content and makes no request. Use it to preview the design. |
A Content Security Policy must allow https://assets.refref.ai in script-src and the API host in connect-src.
Control the panel
| Call | Effect |
|---|---|
window.RefRef.open() | Opens the panel |
window.RefRef.close() | Closes the panel |
window.RefRef.toggle() | Opens or closes the panel |
window.RefRef.isOpen | true when the panel is open |
window.RefRef.setConfig({…}) | Changes design fields on this page, for example triggerText |
window.RefRef.getConfig() | Returns the current design |
The Widget emits no events.
Design the Widget
Set the design for each Program on its Design tab in the Console. RefRef sends it to the Widget at init. The Design tab sets the colors through cssVariables. Under How it works, you can add your own notes and a link to your program terms; the help button of the Widget shows them below the steps that RefRef writes from your rules.
| Field | Values | Default |
|---|---|---|
position | bottom-right, bottom-left, top-right, top-left | bottom-right |
triggerText | The button text | Refer & Earn |
icon | gift, heart, star, zap | gift |
title, subtitle | The panel heading and the text below it | Title: Invite your friends |
logoUrl | An image URL | None |
shareMessage | The text of a share; {productName} is replaced | Join me on {productName} and get a reward! |
enabledPlatforms | facebook, twitter (X), linkedin, whatsapp, email, instagram, telegram | All on except Instagram and Telegram |
cssVariables | CSS custom properties for the Widget's colors, radius, and font | The Widget theme |
The Widget renders in a shadow root, so your page's CSS does not reach it. Change its look with cssVariables. Instagram has no share URL: its button copies the message and the link.
What the customer sees
| Init status | When | The Widget shows |
|---|---|---|
enrolled | The customer has an open enrollment in the token's Program, and the Program is active | The button and panel |
not_enrolled | The customer's enrollment ended, the Program is not active, or the participant limit pauses new enrollments | Only the Rewards tab when the customer was enrolled in the Program, else nothing |
The panel shows one referral link, https://r.refref.ai/<code> (or https://<your-domain>/<code> when the Project has an active custom link domain), with a copy button and the share buttons.
Payout details
A customer with a cash Reward in US dollars that RefRef pays out also sees the amounts on hold, ready, and paid on the Rewards tab, next to the total earned. With a widget:payout token, the payout method button opens a form where the customer enters their country and PayPal address and accepts the payout terms. RefRef pays only a customer who saved these details. See Rewards and delivery.
Troubleshooting
| Symptom | Check |
|---|---|
| No button appears | The token's Program must be active, and the customer's enrollment must not have ended. Check the init answer in the Network tab. |
401 AUTH_REQUIRED | Token signature, typ header, aud, programId of an existing Program, lifetime of at most 3 hours, and the secret of the Program's Project |
403 FORBIDDEN | The token lacks the scope |
400 INVALID_REQUEST | The token names an affiliate or loyalty Program. The Widget shows only a referral Program. |
| The wrong customer's link | sub and participantKind must match the IDs that your backend sends for that customer |
Never put the client secret or a Workspace API key in browser code. The browser gets only the short-lived Widget token.