Referral Widget

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 worksCopy Anchor Link

1. Your backend enrolls the customer in a referral Program (POST /v1/enrollments) and creates their code (POST /v1/referral-codes), or you enroll them in the Console.
2. Your backend signs a short-lived Widget token for the signed-in customer with the Project's client secret.
3. The page loads the Widget script and calls window.RefRef.init with the token.
4. 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.

The Widget renders only for an enrolled customer who has a referral code. Widget initialization never enrolls a customer, creates a code, or records an Event.

1. Sign the token on your backendCopy Anchor Link

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:

widget:read lets the Widget show the link and the payout amounts. widget:payout also lets the customer save their payout details. RefRef drops other claims.

This Node.js example uses the jose library:

import { SignJWT } from "jose";

export async function widgetToken(userId: string) {
  const projectId = process.env.REFREF_PROJECT_ID!;
  return new SignJWT({
    projectId,
    participantKind: "individual",
    scope: "widget:read widget:payout",
  })
    .setProtectedHeader({ alg: "HS256", typ: "refref-widget+jwt" })
    .setIssuer(projectId)
    .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.

2. Load the WidgetCopy Anchor Link

<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",
      {
        projectId: "YOUR_PROJECT_ID",
        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.

A Content Security Policy must allow https://assets.refref.ai in script-src and the API host in connect-src.

Control the panelCopy Anchor Link

The Widget emits no events.

Design the WidgetCopy Anchor Link

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.

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 seesCopy Anchor Link

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 detailsCopy Anchor Link

A customer with a cash Reward in US dollars that RefRef pays out also sees a payout section: the amounts on hold, ready for payout, in progress, and paid. With a widget:payout token, the customer can enter their country and PayPal address and accept the payout terms. RefRef pays only a customer who saved these details. See Rewards and delivery.

TroubleshootingCopy Anchor Link