PlatformInstallation
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
- User logs into your application
- Your backend generates a JWT token for the user (using their
externalId) - Widget is embedded on your page with the JWT token
- Widget fetches the user's refcodes, programs, and stats from RefRef API
- 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);