Configuration & API

Advanced Configuration

Tracker Configuration

window.usertraxConfig = {
  // API endpoint (unified for all events)
  endpoint: "https://api.usertrax.io/api/events",

  // Cross-domain settings
  crossDomainParamName: "uxs",
  crossDomainDomains: ["checkout.example.com"],

  // Session & privacy
  sessionTimeout: 24 * 60 * 60 * 1000, // 24 hours of inactivity
  respectDoNotTrack: false,

  // Silence tracking on selected paths (SPA-aware)
  disableOnPages: ["/form/*"],

  // Ads / marketing forwarding (all off by default)
  ads: false, // Legacy: enables ga4 + tagManager + facebook
  ga4: false,
  tagManager: false,
  facebook: false,
  posthog: false,
};

Set window.usertraxConfig before loading the tracker script.

Configuration Options

Option	Type	Default	Description
`endpoint`	string	`https://api.usertrax.io/api/events`	Unified ingest URL for all tracker events
`crossDomainParamName`	string	`"uxs"`	URL parameter name for the session ID
`crossDomainDomains`	array	`[]`	Domains for cross-domain tracking (`[]` = all)
`sessionTimeout`	number	`86400000` (24h)	Session TTL in milliseconds (inactivity)
`respectDoNotTrack`	boolean	`false`	When `true`, stop tracking if the browser DNT flag is set
`disableOnPages`	array	`[]`	Paths with tracking off (exact strings, `*` globs, `RegExp`, or `(pathname, location) => boolean`; SPA-aware). Session ID in `localStorage` is kept
`ads`	boolean	`false`	Legacy shorthand: enables `ga4`, `tagManager`, and `facebook` together
`ga4`	boolean	`false`	Forward conversions to `gtag` (GA4)
`tagManager`	boolean	`false`	Forward conversions to `dataLayer` (GTM)
`facebook`	boolean	`false`	Forward conversions to `fbq` (Meta Pixel)
`posthog`	boolean	`false`	Forward events/`identify` to `window.posthog`

Details on ads forwarding and Enhanced Conversions: Ads & Enhanced Conversions.

Error Handling and Debugging

Inspect configuration and session

// Current configuration
console.log("Config:", window.usertraxConfig);

// Session ID (localStorage)
console.log("Session ID:", localStorage.getItem("uxs_id"));
console.log("Last activity:", localStorage.getItem("uxs_last"));

There is no debugMode flag on the main tracker. Use the Network tab (/api/events) and the values above when debugging.

Common Issues

Missing Auth Key: Ensure the data-key attribute is set on the script tag
CORS Errors: Verify API endpoints are accessible
Parameter Not Captured: Check URL format and parameter names
Session Not Persisting: Verify localStorage is enabled
No ads forwarding: Flags (ga4 / tagManager / facebook / ads) default to false

Best Practices

1. Consistent Event Naming

// Use consistent, descriptive event names
usertrax.push({ event: "product_purchase" });
usertrax.push({ event: "newsletter_signup" });
usertrax.push({ event: "free_trial_start" });

2. Meaningful Metadata

// Include relevant context
usertrax.push({
  event: "purchase",
  total: 99.99,
  metadata: {
    product_category: "electronics",
    product_brand: "Apple",
    checkout_method: "credit_card",
    user_segment: "premium",
  },
});

3. Proper Currency Handling

// Always specify currency for monetary events
usertrax.push({
  event: "purchase",
  total: 99.99,
  currency: "EUR", // Explicit currency
});

4. User Data Privacy

// Only include necessary user data
usertrax.push({
  event: "signup",
  user_data: {
    email: "user@example.com", // Only essential data
    // Avoid sensitive information like passwords
  },
});

API Reference

usertrax.push()

usertrax.push(eventObject);

Parameters:

eventObject (object): Event data with any of the supported parameters

Returns: void

See Events & Parameters for all object keys.

usertrax.identify()

usertrax.identify(distinctId, traits);

Parameters:

distinctId (string): Stable external user id (e.g. database primary key)
traits (object, optional): Person properties; canonical keys merge into user_data, others appear only in meta_data.$usertrax_identify

Returns: void

Details in User Identification.

window.usertrax.getVariant()

window.usertrax.getVariant(testKey);

Parameters:

testKey (string): A/B test identifier

Returns: string - Current variant key or null

window.usertrax.getAssignments()

window.usertrax.getAssignments();

Returns: object - All current A/B test assignments