RefRef LogoRefRef

Attribution Script

Install the RefRef attribution script to track referrals

Overview

The RefRef attribution script is a lightweight JavaScript library that automatically tracks referral codes from URL parameters, stores them in cookies, and populates form fields. This enables accurate attribution of referrals to the right participants.

How It Works

  1. User clicks a referral link (e.g., yoursite.com?refcode=abc1234)
  2. Attribution script detects the refcode URL parameter
  3. Refcode is stored in a cookie (refref-refcode) for 90 days
  4. When the user signs up, the refcode is automatically populated in your form
  5. Your backend receives the refcode with the signup request
  6. You pass the refcode when creating events via the RefRef API
  7. RefRef creates the referral connection and generates rewards

Installation

Step 1: Add the Script Tag

Add the attribution script to your website's <head> tag or before the closing </body> tag:

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

The defer attribute ensures the script runs after the page loads without blocking rendering.

Step 2: Add Hidden Form Field

Add a hidden input field to your signup form with the data-refref attribute:

<form id="signup-form" action="/api/signup" method="POST">
  <input type="email" name="email" required />
  <input type="password" name="password" required />
 
  <!-- RefRef attribution field -->
  <input type="hidden" name="refcode" data-refref="refcode" />
 
  <button type="submit">Sign Up</button>
</form>

The attribution script automatically finds all elements with data-refref="refcode" and populates them with the stored refcode.

Step 3: Capture Refcode in Your Backend

When processing signups, capture the refcode from the form submission:

app.post('/api/signup', async (req, res) => {
  const { email, password, refcode } = req.body;
 
  // Create user in your database
  const user = await createUser({ email, password });
 
  // Store refcode for later use when firing events
  if (refcode) {
    await storeRefcodeForUser(user.id, refcode);
  }
 
  res.json({ success: true, userId: user.id });
});

Step 4: Fire Events with Refcode

When a qualifying event occurs (signup, purchase, etc.), include the refcode in your event creation:

// After user signs up
await fetch('https://api.refref.app/api/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_API_KEY}`
  },
  body: JSON.stringify({
    productId: 'your-product-id',
    externalId: user.id, // Your user's ID
    eventType: 'signup',
    refcode: storedRefcode, // The refcode from attribution
    metadata: {
      email: user.email,
      signupDate: new Date().toISOString()
    }
  })
});

Configuration Options

The attribution script can be configured via data attributes or JavaScript:

Testing Attribution

Verify Script is Loaded

Open your browser's developer console and check for the RefRef script:

// Check if script loaded
console.log(typeof window.RefRef !== 'undefined' ? 'RefRef loaded' : 'RefRef not loaded');

Test with a Sample Refcode

  1. Visit your site with a refcode parameter: https://yoursite.com?refcode=test123
  2. Open browser DevTools → Application → Cookies
  3. Look for a cookie named refref-refcode with value test123
  4. Navigate to your signup page
  5. Inspect the hidden form field - it should contain test123

Test End-to-End Flow

Advanced Usage

Troubleshooting

Privacy & GDPR Compliance

On this page