RefRef LogoRefRef

Referral Widget

Embed the RefRef widget to enable participants to share referrals and track their rewards

The RefRef widget is an embeddable UI component that allows your users (participants) to view their referral codes, share via social platforms, and track their referral performance and rewards.

Features

  • Referral Link Sharing: One-click sharing via Facebook, Twitter (X), LinkedIn, WhatsApp, Email, Instagram, Telegram
  • Performance Tracking: View referral stats and reward progress
  • Customizable UI: Configure colors, branding, position, and text
  • Framework Agnostic: Built with Web Components for use in any JavaScript framework
  • Secure: JWT-based authentication with product-level secrets

How It Works

  1. Embed widget: Add RefRef widget to your application
  2. User shares: User opens widget and shares their referral link via social platforms
  3. Track rewards: User views referral stats and earned rewards

Authentication: The widget can work without JWT authentication, though it's less secure. For production use, we recommend generating JWT tokens on your backend to authenticate users. If "Enforce Referral Authentication" is enabled in your product settings, JWT tokens are required.

Installation

Step 1: Add Widget Script

Include the RefRef widget script on your page:

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

The script uses Web Components and loads asynchronously. No additional dependencies required.

The widget can work without JWT authentication, though JWT tokens are strongly recommended for production use to securely authenticate participants. Generate tokens on your backend using your product's client secret.

JWT authentication is optional by default. However, if "Enforce Referral Authentication" is enabled in your product settings, JWT tokens become required.

Required JWT Claims:

  • sub (string): User's unique identifier in your system
  • productId (string): Your RefRef product ID
  • iat (number): Issued at timestamp (seconds)
  • exp (number): Expiration timestamp (seconds, recommended: 1 hour)

Optional JWT Claims:

  • email (string): User's email address
  • name (string): User's display name

Signing:

  • Algorithm: HS256
  • Secret: Your product's REFREF_CLIENT_SECRET from RefRef dashboard
import jwt from 'jsonwebtoken';
 
function generateWidgetToken(userId: string, productId: string, userEmail?: string, userName?: string) {
  const payload = {
    sub: userId, // User's unique identifier (required)
    productId: productId, // Your RefRef product ID (required)
    email: userEmail, // Optional
    name: userName, // Optional
    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, // Product secret from RefRef dashboard
    { algorithm: 'HS256' }
  );
 
  return token;
}
 
// Express.js route example
app.get('/api/refref-token', (req, res) => {
  const user = req.user; // From your authentication system
  const token = generateWidgetToken(
    user.id,
    'your-product-id',
    user.email,
    user.name
  );
 
  res.json({ token });
});

Security: Never expose your REFREF_CLIENT_SECRET in frontend code! Always generate JWT tokens on your backend.

Step 3: Initialize & Trigger Widget

Basic initialization:

<!DOCTYPE html>
<html>
<head>
  <script src="https://assets.refref.ai/widget.js"></script>
</head>
<body>
  <!-- Your content -->
 
  <script>
    // Initialize widget with JWT token from your backend
    fetch('/api/refref-token')
      .then(res => res.json())
      .then(data => {
        window.RefRef.init({
          productId: 'your-product-id',
          token: data.token
        });
      });
  </script>
</body>
</html>

The widget automatically displays a floating button once initialized. You can trigger it with a custom button or programmatically.

Custom trigger button:

<!-- Add data-refref-trigger attribute to any button -->
<button data-refref-trigger>Refer & Earn</button>

Programmatic control:

// Open widget programmatically
window.RefRef.open();
 
// Close widget
window.RefRef.close();
 
// Toggle widget
window.RefRef.toggle();

Without JWT (Less Secure):

If JWT authentication is optional for your product, you can initialize with just externalId:

window.RefRef.init({
  productId: 'your-product-id',
  externalId: 'user-123' // Your user's unique identifier
});

For production use, we strongly recommend using JWT tokens. Initialize without a token only if "Enforce Referral Authentication" is disabled in your product settings.

Configuration

Widget configuration is managed in your RefRef dashboard and automatically fetched by the widget. Manual configuration override via widget attributes is not currently supported.

Troubleshooting

  • Attribution Script - Track referral codes automatically
  • Programs - Configure referral programs and reward rules
  • Products - Manage product settings and widget configuration

On this page