Events & Parameters

Basic Event Tracking

Simple Event

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

Ecommerce event (GA4 shape)

usertrax.push({
  event: "purchase",
  event_id: "purchase_10001",
  currency: "EUR",
  value: 99.99,              // alias for total
  total: 99.99,              // contract field
  transaction_id: "10001",   // order number
  tax: 15.96,
  shipping: 5.9,
  items: [
    {
      item_id: "SKU-123",
      item_name: "iPhone 15 Pro",
      item_brand: "Apple",
      item_category: "smartphones",
      price: 47.05,
      quantity: 2,
    },
  ],
  user_data: {
    email: "user@example.com",
    customer_id: "cust_12345",
  },
});

Complete Event with All Parameters

usertrax.push({
  // Required parameters
  event: "purchase",
  total: 99.99,
  currency: "EUR",

  // Optional parameters
  id: "purchase_order_12345", // dedupe / CAPI event_id (alias: event_id)
  event_id: "purchase_order_12345",
  transaction_id: "order_12345",
  label: "iPhone 15 Pro",
  tax: 15.96,
  shipping: 5.9,

  // Attribution parameters (auto-captured)
  gclid: "abc123def456",
  fbclid: "fb.123.456.789",
  msclkid: "ms123456789",
  ttclid: "tt123456789",

  // UTM parameters
  utm: {
    utm_source: "google",
    utm_medium: "cpc",
    utm_campaign: "summer_sale",
    utm_term: "iphone",
    utm_content: "banner_ad",
  },

  // GA4 items[]
  items: [
    {
      item_id: "iphone_15_pro",
      item_name: "iPhone 15 Pro",
      item_brand: "Apple",
      item_category: "smartphones",
      price: 99.99,
      quantity: 1,
    },
  ],

  // Custom metadata
  metadata: {
    plan: "pro",
  },

  // User data
  user_data: {
    email: "user@example.com",
    name: "John Doe",
    phone: "+1234567890",
    customer_id: "cust_12345",
  },
});

Available Object Keys

Core Event Parameters

Parameter	Type	Required	Description
`event`	string	Yes	Event name (e.g. `"purchase"`, `"add_to_cart"`, `"view_item"`)
`total`	number	No	Conversion value/amount (primary contract)
`value`	number	No	Alias for `total` (GA4-style; normalized to `total`)
`currency`	string	No	Currency code (default: `"EUR"`)
`id`	string	No	Dedupe ID (server/`event_id`, Meta `eventID`)
`event_id`	string	No	Preferred dedupe ID (`event_id ?? id`)
`transaction_id`	string	No	Order number (ads `transaction_id`, Meta/CAPI `order_id`)
`label`	string	No	Human-readable label
`tax`	number	No	Tax portion
`shipping`	number	No	Shipping cost
`shipping_tier`	string	No	Shipping method
`payment_type`	string	No	Payment method
`coupon`	string	No	Coupon code
`items`	array	No	GA4 ecommerce items (`item_id`, `item_name`, `price`, `quantity`, …)

Attribution Parameters

Parameter	Type	Description
`gclid`	string	Google Ads Click ID
`gclsrc`	string	Google Ads Click Source
`dclid`	string	Display & Video 360 Click ID
`fbclid`	string	Facebook Ads Click ID
`fbc`	string	Facebook Browser Cookie
`fbp`	string	Facebook Browser Parameter
`msclkid`	string	Microsoft Ads Click ID
`ttclid`	string	TikTok Ads Click ID
`adcell`	string	Adcell Tracker ID

UTM Parameters

Parameter	Type	Description
`utm_source`	string	Traffic source (e.g., “google”, “facebook”)
`utm_medium`	string	Marketing medium (e.g., “cpc”, “email”)
`utm_campaign`	string	Campaign name
`utm_term`	string	Keywords for paid search
`utm_content`	string	Content variation for A/B testing

Custom Data

Parameter	Type	Description
`metadata`	object	Custom JSON data for the conversion
`user_data`	object	User information (email, name, etc.)

HTML Data Attributes

Basic Tracking

<button
  data-usertrax="purchase"
  data-usertrax-total="99.99"
  data-usertrax-currency="EUR"
  data-usertrax-id="order_12345"
  data-usertrax-label="iPhone 15 Pro"
>
  Buy Now
</button>

Advanced Tracking with Metadata

<button
  data-usertrax="signup"
  data-usertrax-total="0"
  data-usertrax-currency="EUR"
  data-usertrax-meta-data='{"plan": "premium", "source": "landing_page"}'
  data-usertrax-user-data='{"email": "user@example.com"}'
>
  Start Free Trial
</button>

Available Data Attributes

Attribute	Description
`data-usertrax`	Event name
`data-usertrax-total`	Conversion value
`data-usertrax-value`	Alias for `data-usertrax-total`
`data-usertrax-currency`	Currency code
`data-usertrax-id`	Event identifier
`data-usertrax-label`	Event label
`data-usertrax-meta-data`	JSON string with custom data
`data-usertrax-user-data`	JSON string with user information