Ads & Enhanced Conversions

The tracker can forward conversions to GA4, Google Tag Manager, and Meta/Facebook. Everything is disabled by default.

// Legacy: enable everything at once (GA4, Tag Manager, Facebook)
window.usertraxConfig = { ads: true };

// Granular: only what you need
window.usertraxConfig = {
  ga4: true,         // gtag('event', ...) → Google Analytics 4
  tagManager: true,  // dataLayer.push(...) → Google Tag Manager
  facebook: true,    // fbq('track' / 'trackCustom', ...) → Meta Pixel
};

ads: true is a legacy shorthand that enables ga4, tagManager, and facebook together. Individual flags are the alternative when you don’t want to use ads.

• Sends gtag('event', eventName, params) with:
  • value (from total/value), currency, transaction_id (from transaction_id/id), event_label (from label)
  • optional tax, shipping, shipping_tier, payment_type, coupon, items[]
  • UTM parameters as utm_*
  • Click IDs: gclid, msclkid, fbclid, ttclid
  • Primitive metadata fields as meta_*

• Flat dataLayer push including metadata, utm, event_source: 'usertrax', optional event_id
• When items[] is set, additionally:
  1. { ecommerce: null } (clear)
  2. Nested push { event, event_source, event_id?, ecommerce: { currency, value, transaction_id, items, … } }

Known event names are sent as standard events (fbq('track', …)); everything else stays custom (trackCustom):

Payload includes:

• value, currency, transaction_id
• from items[]: content_type: 'product', content_ids, contents (id, quantity, item_price), num_items
• Dedup: { eventID } from event_id / id (same value as server-side CAPI)

Example:

usertrax.push({
  event: "purchase",
  total: 99.99,
  currency: "EUR",
  event_id: "purchase_order_123",
  transaction_id: "order_123",
  items: [
    { item_id: "SKU-1", item_name: "Product", price: 99.99, quantity: 1 },
  ],
});

Enable enhanced conversions by setting user-provided data. The tracker normalizes (trim/lowercase) and SHA‑256 hashes these fields in the browser, then sets GA4 user data via gtag('set','user_data', ...) and/or pushes to the GTM dataLayer — depending on whether ga4 and/or tagManager (or legacy ads: true) is enabled.

Supported fields:

• email, phone/phone_number
• first_name, last_name
• address: street/street_address/address, city, region/state, postal_code/zip, country/country_code

Requirements: Runs in the browser with crypto.subtle (HTTPS, modern browsers).

window.usertrax.setUserData({
  email: "john@example.com",
  phone: "+1 555 123 4567",
  first_name: "John",
  last_name: "Doe",
  address: {
    street: "123 Main St",
    city: "Anytown",
    region: "CA",
    postal_code: "94016",
    country: "US",
  },
});

await tracker.setUserData({
  email: "john@example.com",
  phone: "+1 555 123 4567",
  first_name: "John",
  last_name: "Doe",
  address: {
    street: "123 Main St",
    city: "Anytown",
    region: "CA",
    postal_code: "94016",
    country: "US",
  },
});

For a persistent person id and traits on all events, see User Identification.