Skip to content
usertraxusertraxDocumentation

Standard Integration

Connect usertrax with any website to automatically track conversions and optimize your marketing campaigns.

Installation

Section titled “Installation”

1. Include Tracking Script

Section titled “1. Include Tracking Script”

Add the usertrax tracking script to the <head> section of your HTML pages:

<script src="https://usertrax.io/cvs.js" data-key="YOUR_API_KEY"></script>

Important: Replace YOUR_API_KEY with your actual API key from the usertrax dashboard.

2. Script Position

Section titled “2. Script Position”

The script should be loaded as early as possible in the <head> section to capture all conversions:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Your Website</title>


    <!-- usertrax Tracking Script -->
    <script src="https://usertrax.io/cvs.js" data-key="YOUR_API_KEY"></script>
  </head>
  <body>
    <!-- Your website content -->
  </body>
</html>

Configuration

Section titled “Configuration”

Advanced Configuration

Section titled “Advanced Configuration”

You can customize the tracking behavior by defining usertraxConfig before loading the script:

<script>
  window.usertraxConfig = {
    endpoint: "https://api.usertrax.io/api/events",
    crossDomainParamName: "uxs",
    crossDomainDomains: [],
    sessionTimeout: 24 * 60 * 60 * 1000,
    respectDoNotTrack: false,
    // Ads/marketing forwarding (disabled by default)
    ads: false,
    ga4: false,
    tagManager: false,
    facebook: false,
    posthog: false,
    // Silence tracking on selected paths (SPA-aware; session ID is kept)
    disableOnPages: ["/form/*", "/checkout"],
  };
</script>
<script src="https://usertrax.io/cvs.js" data-key="YOUR_API_KEY"></script>

disableOnPages supports exact paths, * globs (e.g. /form/*), RegExp, and (pathname, location) => boolean functions. On matching routes no API requests are sent (session, conversions, ads forwarding). The session ID in localStorage is preserved. On SPA navigation from a disabled to an enabled route, the session starts lazily.

Events are routed via the type field:

typePurpose
sessionSession init + A/B config (on page load)
conversionConversions via usertrax.push or clicks

Legacy endpoints /api/tracker/conversion and /api/tracker/session remain for older cached scripts. /api/tracker/events is an alias for /api/events.

First-Party Proxy (Ad Blocker Bypass)

Section titled “First-Party Proxy (Ad Blocker Bypass)”

To route the tracking script and events through your own domain, see the Proxy Guides.

Conversion Tracking

Section titled “Conversion Tracking”

1. Automatic Tracking

Section titled “1. Automatic Tracking”

The script automatically captures on page load:

  • Sessions: User sessions are created and sent to the API
  • A/B tests: Active tests are loaded and variants applied
  • Tracking parameters: UTM parameters, Google Ads, Facebook, Microsoft Ads IDs

2. Manual Conversion Tracking

Section titled “2. Manual Conversion Tracking”

Use the usertrax.push() function for custom conversions:

// Simple conversion
usertrax.push({
  event: "purchase",
  total: 99.99,
  currency: "EUR",
});


// Detailed conversion with metadata
usertrax.push({
  event: "form_submit",
  id: "lead_12345",
  label: "Newsletter Signup",
  total: 0,
  currency: "EUR",
  metadata: {
    form_type: "newsletter",
    page: "homepage",
  },
});

3. HTML Attributes for Automatic Tracking

Section titled “3. HTML Attributes for Automatic Tracking”

Use data-usertrax attributes for automatic event tracking:

<!-- Simple event -->
<button data-usertrax="button_click">Click me</button>


<!-- Event with value -->
<button
  data-usertrax="purchase"
  data-usertrax-total="49.99"
  data-usertrax-currency="EUR"
>
  Buy Now
</button>


<!-- Event with metadata -->
<form data-usertrax="form_submit" data-usertrax-label="Contact Form">
  <!-- Form content -->
</form>

A/B Testing Integration

Section titled “A/B Testing Integration”

1. HTML Elements for A/B Tests

Section titled “1. HTML Elements for A/B Tests”

Use special attributes for A/B testing:

<!-- Variant A -->
<div
  data-usertrax-ab-test-group="headline_test"
  data-usertrax-ab-test-variant="A"
>
  <h1>Welcome to our site!</h1>
</div>


<!-- Variant B -->
<div
  data-usertrax-ab-test-group="headline_test"
  data-usertrax-ab-test-variant="B"
>
  <h1>Discover our offers!</h1>
</div>


<!-- Fallback (shown when no test is active) -->
<div data-usertrax-ab-test-group="headline_test" data-usertrax-ab-test-fallback>
  <h1>Welcome!</h1>
</div>

2. JavaScript for A/B Tests

Section titled “2. JavaScript for A/B Tests”
// Get current variant
const variant = usertrax.getVariant("headline_test");


// Get all A/B test assignments
const assignments = usertrax.getAssignments();


// Manually apply element visibility
usertrax.applyElementVisibility();

Cross-Domain Tracking

Section titled “Cross-Domain Tracking”

Configuration

Section titled “Configuration”

Enable cross-domain tracking for multiple domains:

window.usertraxConfig = {
  crossDomainParamName: "uxs",
  crossDomainDomains: [
    "shop.example.com",
    "blog.example.com",
    "landing.example.com",
  ],
};

How it Works

Section titled “How it Works”
  1. Session ID added to URLs: When clicking external links, the session ID is automatically added as a URL parameter
  2. Automatic detection: The script recognizes the session ID on the target page
  3. Seamless tracking: Conversions are attributed to the original session

Tracking Parameters

Section titled “Tracking Parameters”

Automatically Captured Parameters

Section titled “Automatically Captured Parameters”

The script automatically captures the following tracking parameters:

  • Google Ads: gclid, gclsrc, dclid
  • Facebook Ads: fbclid, fbc, fbp
  • Microsoft Ads: msclkid
  • TikTok Ads: ttclid
  • UTM Parameters: utm_source, utm_medium, utm_campaign, etc.

Parameter Storage

Section titled “Parameter Storage”

Parameters are automatically stored in localStorage and sent with conversions:

// Parameters are automatically captured and stored
// https://your-website.com/?gclid=abc123&utm_source=google


// At the next conversion, these parameters are automatically included
usertrax.push({
  event: "purchase",
  total: 99.99,
  // gclid and utm_source are automatically added
});

Examples

Section titled “Examples”

E-Commerce Conversion

Section titled “E-Commerce Conversion”
// Product view
usertrax.push({
  event: "view_item",
  id: "product_123",
  label: "iPhone 15 Pro",
  total: 1199.0,
  currency: "EUR",
  metadata: {
    category: "Smartphones",
    brand: "Apple",
  },
});


// Add to cart
usertrax.push({
  event: "add_to_cart",
  id: "product_123",
  label: "iPhone 15 Pro",
  total: 1199.0,
  currency: "EUR",
});


// Complete purchase
usertrax.push({
  event: "purchase",
  id: "order_45678",
  label: "iPhone 15 Pro",
  total: 1199.0,
  currency: "EUR",
  metadata: {
    order_id: "45678",
    payment_method: "credit_card",
  },
});

Lead Generation

Section titled “Lead Generation”
<!-- Contact form -->
<form
  id="contact-form"
  data-usertrax="form_submit"
  data-usertrax-label="Contact Form"
>
  <input type="text" name="name" placeholder="Name" required />
  <input type="email" name="email" placeholder="Email" required />
  <button type="submit">Submit</button>
</form>


<script>
  document
    .getElementById("contact-form")
    .addEventListener("submit", function (e) {
      // Form is automatically tracked via data-usertrax attributes


      // Add additional metadata
      usertrax.push({
        event: "lead_generated",
        label: "Contact Form",
        metadata: {
          form_type: "contact",
          page: "contact",
        },
      });
    });
</script>

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”
  1. Script not loading: Check the URL and API key
  2. No conversions: Ensure the API key is correct
  3. Cross-domain not working: Check the domain configuration

Browser Console

Section titled “Browser Console”

Check the browser console for error messages and tracking logs (e.g. “Session initialized”, “Conversion sent successfully”).

Privacy

Section titled “Privacy”

GDPR Compliance

Section titled “GDPR Compliance”
  • No cookies: The script doesn’t use cookies
  • Local storage: Tracking parameters are only stored locally
  • Opt-out: Users can disable tracking through browser settings

Privacy Policy

Section titled “Privacy Policy”

Add the following information to your privacy policy:

“This website uses usertrax for conversion tracking. No cookies are set, but tracking parameters are stored locally. For more information, see the usertrax privacy policy.”

Support

Section titled “Support”

For questions or issues: