RefRef LogoRefRef

Referral Widget

Embed the RefRef widget to enable participant referrals

Overview

The RefRef widget is an embeddable UI component that allows participants (your users) to:

  • View their unique referral codes and links
  • Share referrals via social media, email, or copy link
  • Track their referral performance and rewards
  • See their referral history

The widget is built with Web Components for framework-agnostic integration and uses Shadow DOM for style isolation.

How It Works

  1. User logs into your application
  2. Your backend generates a JWT token for the user (using their externalId)
  3. Widget is embedded on your page with the JWT token
  4. Widget fetches the user's refcodes, programs, and stats from RefRef API
  5. User can share their referral link and track performance

Installation

Step 1: Add the Widget Script

Add the widget script to your page:

<script src="https://assets.refref.app/widget.js" defer></script>

Step 2: Generate JWT Token (Backend)

The widget requires a JWT token to authenticate the participant. Generate this token on your backend:

import jwt from 'jsonwebtoken';
 
function generateWidgetToken(userId: string, productId: string) {
  const payload = {
    externalId: userId, // Your user's ID
    productId: productId, // Your RefRef product ID
    iat: Math.floor(Date.now() / 1000),
    exp: Math.floor(Date.now() / 1000) + (60 * 60) // 1 hour expiry
  };
 
  const token = jwt.sign(
    payload,
    process.env.REFREF_CLIENT_SECRET, // Your product's client secret
    { algorithm: 'HS256' }
  );
 
  return token;
}
 
// API route example
app.get('/api/refref-token', async (req, res) => {
  const userId = req.user.id; // From your auth system
  const token = generateWidgetToken(userId, 'your-product-id');
 
  res.json({ token });
});

Never expose your client secret in frontend code! Always generate the JWT on your backend.

Step 3: Embed the Widget

Add the widget component to your page:

<!DOCTYPE html>
<html>
<head>
  <script src="https://assets.refref.app/widget.js" defer></script>
</head>
<body>
  <div id="refref-widget-container">
    <refref-widget
      product-id="your-product-id"
      token="USER_JWT_TOKEN">
    </refref-widget>
  </div>
 
  <script>
    // Fetch token from your backend
    async function loadWidget() {
      const response = await fetch('/api/refref-token');
      const { token } = await response.json();
 
      const widget = document.querySelector('refref-widget');
      widget.setAttribute('token', token);
    }
 
    loadWidget();
  </script>
</body>
</html>

Widget Attributes

Customization

Styling

The widget uses Shadow DOM for style isolation, but you can customize via CSS custom properties:

refref-widget {
  --refref-primary-color: #3b82f6;
  --refref-border-radius: 8px;
  --refref-font-family: 'Inter', sans-serif;
  --refref-background: #ffffff;
  --refref-text-color: #1f2937;
}
 
/* Dark theme */
refref-widget[theme="dark"] {
  --refref-background: #1f2937;
  --refref-text-color: #f9fafb;
}

Layout

Control widget width and height:

refref-widget {
  display: block;
  width: 100%;
  max-width: 600px;
  margin: 0 auto;
}

Widget Features

Events

Listen to widget events in your application:

const widget = document.querySelector('refref-widget');
 
// When user copies referral link
widget.addEventListener('refref:link-copied', (event) => {
  console.log('Link copied:', event.detail.link);
  // Show success toast
});
 
// When user shares on social media
widget.addEventListener('refref:shared', (event) => {
  console.log('Shared on:', event.detail.platform);
  // Track analytics
});
 
// When widget loads successfully
widget.addEventListener('refref:loaded', (event) => {
  console.log('Widget loaded:', event.detail);
});
 
// When widget encounters an error
widget.addEventListener('refref:error', (event) => {
  console.error('Widget error:', event.detail.message);
});

Programmatic Control

Control the widget via JavaScript:

const widget = document.querySelector('refref-widget');
 
// Refresh widget data
widget.refresh();
 
// Generate new refcode
await widget.generateRefcode();
 
// Get current participant data
const participant = await widget.getParticipant();
console.log('Participant:', participant);
 
// Get referral stats
const stats = await widget.getStats();
console.log('Stats:', stats);

Testing the Widget

Troubleshooting

Security Best Practices

Advanced Usage

Previous

Attribution Script

Next

Projects

On this page