refVenuerefVenue
Docs
JavaScript Integration

JavaScript Integration

Add refVenue tracking to your website with our JavaScript snippet

JavaScript Integration

The easiest way to add affiliate tracking to your website is with our JavaScript snippet.

Installation

Step 1: Get Your Keys

  1. Log in to refVenue
  2. Go to Settings → API Keys/Secrets
  3. Copy your Publishable Key
  4. Note your Program ID from the Programs page

Step 2: Add the Script

Add this to your website's <head> section:

<script async src="https://yourdomain.com/refvenue.js"
        data-refvenue="YOUR_PUBLISHABLE_KEY"
        data-program-id="YOUR_PROGRAM_ID"></script>

Replace:

  • yourdomain.com with your actual domain
  • YOUR_PUBLISHABLE_KEY with your publishable key
  • YOUR_PROGRAM_ID with your program ID

Step 3: Track Conversions

Add tracking calls after successful conversions:

<!-- After user signs up -->
<script>
trackRegistration('user@example.com');
</script>
 
<!-- After user makes a purchase -->
<script>
trackPurchase('user@example.com', 99.99);
</script>

Tracking Functions

trackRegistration(email)

Tracks user registrations/signups.

Parameters:

  • email (string, required): Customer's email address

Example:

trackRegistration('customer@example.com');

When to use:

  • After successful user registration
  • After email verification
  • After account creation

trackPurchase(emailOrCoupon, amount)

Tracks purchases. Automatically detects email vs coupon code.

Parameters:

  • emailOrCoupon (string, required): Customer email OR coupon code
  • amount (number, required): Purchase amount (after discount)

Examples:

With Email (Referral Tracking):

trackPurchase('customer@example.com', 99.99);

With Coupon Code:

trackPurchase('SAVE20', 80.00);  // Pass post-discount amount

When to use:

  • After successful payment
  • After order confirmation
  • After checkout completion

Important: Always pass the net amount (after discounts), not the original price.

How It Works

Automatic Click Tracking

The script automatically:

  1. Detects ?ref=CODE in the URL
  2. Stores the affiliate code in a cookie
  3. Tracks the page visit
  4. Associates future conversions with that affiliate

Cookie Management

Cookie Name: affiliate_ref Duration: Configurable per program (default: 30 days) Scope: Domain-wide (works across subdomains)

Email vs Coupon Detection

When you call trackPurchase(), the script:

  1. Checks if first parameter is an email (regex validation)
  2. If email: Uses ref_code from cookie, requires prior click
  3. If coupon: Uses coupon_code, no click needed
// This is detected as EMAIL
trackPurchase('user@example.com', 99.99);
// → Sends: { ref_code: 'JOHN123', customer_email: 'user@example.com' }
 
// This is detected as COUPON CODE
trackPurchase('SAVE20', 80.00);
// → Sends: { coupon_code: 'SAVE20', revenue_amount: 80.00 }

Implementation Examples

React/Next.js

// Add to _app.js or layout
useEffect(() => {
  // Script is already loaded via <script> tag in HTML
}, []);
 
// After signup
const handleSignup = async (email) => {
  await createUserAccount(email);
 
  // Track the registration
  if (window.trackRegistration) {
    window.trackRegistration(email);
  }
};
 
// After purchase
const handlePurchase = async (email, amount) => {
  await processPayment(email, amount);
 
  // Track the purchase
  if (window.trackPurchase) {
    window.trackPurchase(email, amount);
  }
};

Vue.js

// After signup
methods: {
  async completeSignup() {
    await this.createAccount();
 
    if (window.trackRegistration) {
      window.trackRegistration(this.user.email);
    }
  }
}
 
// After purchase
methods: {
  async completePurchase() {
    const total = this.cart.total;
    await this.processPayment();
 
    if (window.trackPurchase) {
      window.trackPurchase(this.user.email, total);
    }
  }
}

WordPress

Add to your theme's functions.php:

// Add tracking script to header
function add_refvenue_script() {
  ?>
  <script async src="https://yourdomain.com/refvenue.js"
          data-refvenue="YOUR_PUBLISHABLE_KEY"
          data-program-id="YOUR_PROGRAM_ID"></script>
  <?php
}
add_action('wp_head', 'add_refvenue_script');
 
// Track after WooCommerce purchase
function track_woocommerce_purchase($order_id) {
  $order = wc_get_order($order_id);
  $email = $order->get_billing_email();
  $total = $order->get_total();
  ?>
  <script>
  if (window.trackPurchase) {
    trackPurchase('<?php echo esc_js($email); ?>', <?php echo $total; ?>);
  }
  </script>
  <?php
}
add_action('woocommerce_thankyou', 'track_woocommerce_purchase');

Shopify

<!-- Add to Settings → Checkout → Order Status Page -->
<script async src="https://yourdomain.com/refvenue.js"
        data-refvenue="YOUR_PUBLISHABLE_KEY"
        data-program-id="YOUR_PROGRAM_ID"></script>
 
<script>
// Track purchase
if (window.trackPurchase) {
  trackPurchase('{{ order.email }}', {{ total_price | money_without_currency }});
}
</script>

Coupon Tracking

Scenario: Customer Uses Coupon at Checkout

// In your checkout flow
const appliedCoupon = 'SAVE20';  // From checkout form
const discountedTotal = 80.00;   // After applying coupon
 
// On purchase success
trackPurchase(appliedCoupon, discountedTotal);

What happens:

  1. Script detects 'SAVE20' is not an email
  2. Sends coupon_code: 'SAVE20' to API
  3. refVenue looks up the coupon's owner
  4. Credits that affiliate with the conversion
  5. No prior referral click required!

Advanced Configuration

Custom Tracking URL

If your tracking server is on a different port/domain:

<script async src="https://yourdomain.com/refvenue.js"
        data-refvenue="YOUR_KEY"
        data-program-id="YOUR_PROGRAM_ID"
        data-tracking-url="http://localhost:3000"></script>

Debug Mode

Check the browser console for tracking activity:

// The script logs:
"refVenue: Affiliate tracking enabled: JOHN123"
"refVenue: Visit tracked successfully"
"refVenue: Registration tracked successfully!"
"refVenue: Purchase tracked successfully!"

Error Handling

// Wrap in try-catch for safety
try {
  if (window.trackPurchase) {
    trackPurchase(email, amount);
  }
} catch (error) {
  console.error('Tracking error:', error);
  // Don't block user flow on tracking errors
}

Troubleshooting

Tracking Not Working

Check Console:

  • Open browser DevTools → Console
  • Look for refVenue messages
  • Check for errors

Common Issues:

  1. Script not loaded: Check <script> tag is in <head>
  2. Wrong keys: Verify publishable key and program ID
  3. Ad blockers: Some block tracking scripts
  4. CORS errors: Check data-tracking-url if using custom domain

Conversions Not Appearing

Verify:

  1. Function exists: console.log(window.trackPurchase)
  2. Called after success: Place call after payment confirms
  3. Correct parameters: Email format or valid coupon code
  4. Network request sent: Check Network tab in DevTools

Rate Limiting

If you see "Rate limit exceeded" in console:

  • Clicks: Max 5/hour, 20/day per visitor
  • Conversions: Max 2/hour, 10/day per affiliate
  • This prevents fraud, not normal usage

Best Practices

Timing

Call tracking after success confirmation:

// ✅ Good
await processPayment();
trackPurchase(email, amount);
 
// ❌ Bad
trackPurchase(email, amount);
await processPayment();  // What if this fails?

Amount Precision

Always pass the post-discount amount:

// ✅ Good
const total = 100;
const discount = 20;
const finalAmount = total - discount;  // 80
trackPurchase(email, finalAmount);
 
// ❌ Bad
trackPurchase(email, 100);  // Wrong! Overpays commission

Email Privacy

Never track without user consent:

  • Follow GDPR/privacy laws
  • Get user consent for tracking
  • Include in privacy policy
  • Respect Do Not Track settings (optional)

Next Steps

Support

Payout SetupServer-Side Tracking