Universal Script API Reference & Recipes

Tracking & Analytics

The ClickerVolt JavaScript API provides powerful functions for tracking conversions, events, and visitor data directly on your web pages. This guide covers practical examples and common recipes for real-world scenarios.

Getting Started

Add the Universal Tracking Script to your page (available in your target's conversion tracking settings). This single script provides all API functions and automatically loads without blocking your page.

<script>
  // Universal Tracking Script
  // (Copy from ClickerVolt - one script for all tracking)
</script>

The script provides two key interfaces: Global Functions (cvEvent, cvConvert, cvIdentify, cvWaitFor) and the window.CV Object for accessing tracking data.

Core Functions

cvConvert(targetId, revenue?, transaction?) - Track conversions with optional revenue and transaction ID for deduplication.

// Basic conversion
cvConvert('tgt_abc123');

// With revenue
cvConvert('tgt_abc123', 49.99);

// With revenue and transaction ID (recommended)
cvConvert('tgt_abc123', 149.99, 'order_12345');

cvEvent(targetId, eventNumber) - Track custom events (1-10) like button clicks, video views, or form interactions.

// Track video view (Event 1)
cvEvent('tgt_abc123', 1);

// Track form submission (Event 2)
cvEvent('tgt_abc123', 2);

// Track add-to-cart (Event 3)
cvEvent('tgt_abc123', 3);

cvIdentify(data) - Capture visitor information (email, name, phone, date of birth, gender) for lead enrichment.

// Email only
cvIdentify({ email: 'user@example.com' });

// Full profile
cvIdentify({
  email: 'john.doe@example.com',
  firstName: 'John',
  lastName: 'Doe',
  phone: '+1234567890',
  dob: '1970-01-01',      // yyyy-mm-dd
  gender: 'm'             // 'm' | 'f'
});

cvWaitFor(selector, callback, timeout?) - Wait for dynamically loaded elements (perfect for SPAs and AJAX content).

// Wait for checkout button
cvWaitFor('#checkout-button', function(button) {
  button.addEventListener('click', function() {
    cvConvert('tgt_abc123', cartTotal);
  });
});

Recipe 1: E-commerce Checkout Flow

Track visitor identity on checkout page and conversion on confirmation page:

// Checkout page - capture customer info
document.getElementById('checkout-form').addEventListener('submit', function() {
  cvIdentify({
    email: document.getElementById('email').value,
    firstName: document.getElementById('first-name').value,
    lastName: document.getElementById('last-name').value
  });
});

// Order confirmation page - track conversion
var orderId = window.orderData.id;
var revenue = window.orderData.total;
cvConvert('tgt_abc123', revenue, orderId);

Recipe 2: Lead Generation Form

Capture lead information and track submission as an event:

document.getElementById('lead-form').addEventListener('submit', function(e) {
  e.preventDefault();

  // Identify visitor
  cvIdentify({
    email: this.querySelector('[name="email"]').value,
    firstName: this.querySelector('[name="firstName"]').value,
    lastName: this.querySelector('[name="lastName"]').value,
    phone: this.querySelector('[name="phone"]').value
  });

  // Track event
  cvEvent('tgt_abc123', 1);

  // Submit form
  this.submit();
});

Recipe 3: Video Engagement Tracking

Track video milestones (25%, 50%, 75%, 100%):

cvWaitFor('.video-player', function(player) {
  // Track milestones
  player.addEventListener('timeupdate', function() {
    var percent = (player.currentTime / player.duration) * 100;

    if (percent >= 25 && !player.tracked25) {
      cvEvent('tgt_abc123', 1); // 25% watched
      player.tracked25 = true;
    }

    if (percent >= 50 && !player.tracked50) {
      cvEvent('tgt_abc123', 2); // 50% watched
      player.tracked50 = true;
    }

    if (percent >= 75 && !player.tracked75) {
      cvEvent('tgt_abc123', 3); // 75% watched
      player.tracked75 = true;
    }
  });

  // Track completion
  player.addEventListener('ended', function() {
    cvEvent('tgt_abc123', 4); // Video completed
  });
});

Recipe 4: SaaS Trial to Paid Conversion

Track trial signup and eventual upgrade:

// Trial signup page
document.getElementById('trial-form').addEventListener('submit', function() {
  cvIdentify({
    email: this.querySelector('[name="email"]').value,
    firstName: this.querySelector('[name="firstName"]').value
  });

  // Track trial signup event
  cvEvent('tgt_abc123', 1);
});

// Upgrade confirmation page
var subscriptionId = 'subscription_' + userId;
cvConvert('tgt_abc123', 49.99, subscriptionId);

Recipe 5: Progressive Profiling

Capture information in stages as the user progresses:

// Step 1: Email popup
document.getElementById('email-popup').addEventListener('submit', function() {
  cvIdentify({
    email: this.querySelector('[name="email"]').value
  });
  cvEvent('tgt_abc123', 1); // Email captured
});

// Step 2: Full registration (later)
document.getElementById('registration-form').addEventListener('submit', function() {
  cvIdentify({
    email: this.querySelector('[name="email"]').value,
    firstName: this.querySelector('[name="firstName"]').value,
    lastName: this.querySelector('[name="lastName"]').value,
    phone: this.querySelector('[name="phone"]').value
  });
  cvEvent('tgt_abc123', 2); // Full registration
});

Recipe 6: Multi-Step Funnel Tracking

Track user progress through a multi-step funnel:

// Step 1: Landing page view (automatic)
// Step 2: Button click
document.getElementById('get-started').addEventListener('click', function() {
  cvEvent('tgt_abc123', 1);
});

// Step 3: Form started
document.getElementById('signup-form').addEventListener('focus', function() {
  cvEvent('tgt_abc123', 2);
}, true);

// Step 4: Form submitted
document.getElementById('signup-form').addEventListener('submit', function() {
  cvEvent('tgt_abc123', 3);
  cvIdentify({ email: this.querySelector('[name="email"]').value });
});

Recipe 7: Add to Cart Tracking

Track when users add products to their cart:

// Single product page
document.getElementById('add-to-cart').addEventListener('click', function() {
  var productPrice = parseFloat(this.dataset.price);
  cvEvent('tgt_abc123', 1);

  // Optional: track product value
  console.log('Product added: $' + productPrice);
});

// Multiple products
document.querySelectorAll('.add-to-cart-btn').forEach(function(btn) {
  btn.addEventListener('click', function() {
    cvEvent('tgt_abc123', 1);
  });
});

Accessing Tracking Data

Use the window.CV object to access tracking information:

// Get visitor ID (for cross-device tracking)
var visitorId = window.CV.getVisitorId();
console.log('Visitor ID:', visitorId);

// Get click ID for a specific target
var clickId = window.CV.getClickId('tgt_abc123');
if (clickId) {
  console.log('User came from tracked link');
}

// Get current page tracking data
var pageData = window.CV.getPageData();
if (pageData) {
  console.log('Page is tracked:', pageData.cid);
}

Best Practices

Always check return values - functions return true on success, false on failure
Use cvWaitFor for dynamic content - prevents errors with AJAX-loaded elements
Always provide transaction IDs for conversions - prevents duplicate tracking
Call cvIdentify before cvConvert when possible - ensures visitor data is captured
Validate input data before calling functions - check for empty values
Use event numbers consistently - document which events track what actions

Error Handling

Always check if functions succeed and handle failures appropriately:

var success = cvEvent('tgt_abc123', 1);
if (!success) {
  console.error('Event tracking failed - check target ID and tracking data');
}

// Validate before calling cvIdentify
var email = form.querySelector('[name="email"]').value;
if (email && email.includes('@')) {
  cvIdentify({ email: email });
} else {
  console.warn('Invalid email, skipping cvIdentify');
}

Common Issues

Function returns false: Check that the target ID is correct and the page has tracking data (click ID in cookie). For cvIdentify, ensure the page has tracking data from a tracked link.

Events not appearing in dashboard: Verify the event number (1-10) is configured in your target settings and has a name assigned.

cvIdentify not working: Confirm the page has tracking data using window.CV.getPageData(). The page must be visited via a tracked link to have a click ID.

Advanced Tips

Queue support: Functions can be called before the external script loads - they're automatically queued and executed when ready
Cross-device tracking: Use window.CV.getVisitorId() to maintain visitor identity across devices
Custom attribution: Access click IDs and pass them to your analytics platform for unified reporting
SPA support: cvWaitFor works perfectly with React, Vue, Angular and other SPAs that dynamically load content