Event Tracking

Upsurge uses storefront events to measure behavior and trigger conversion experiences.

Baseline events

Event	Helper	When to send
page_view	trackPageView	After a shopper views a page; automatic by default.
product_view	trackProductView	After a shopper views a product detail page.
add_to_cart	trackAddToCart	After an item is added to cart.
remove_from_cart	trackRemoveFromCart	After an item is removed from cart.
checkout_start	trackCheckoutStart	When checkout begins.
checkout_complete	trackCheckoutComplete	When checkout completes in integrations that use it as a conversion boundary.
purchase	trackPurchase	After an order is confirmed.
search	trackSearch	After an onsite search.

Example

window.upsurge.track(
  'product_view',
  {
    product_id: 'sku_123',
    product_name: 'Trail Runner',
    product_price: 129.0,
    currency: 'USD',
  },
);

Use window.UpsurgeQueue.push(['track', ...]) only for calls made before the SDK finishes loading. After initialization, call window.upsurge.track(...) directly.

Data quality

• Use stable product IDs from your catalog.
• Send monetary values as numbers in the stated currency and use one representation consistently.
• Include currency when an event contains money.
• Avoid sending sensitive personal data in custom fields.

Commerce payloads

Product

trackProductView requires product_id and accepts product_name, product_category, product_price, currency, and variant.

Cart item

trackAddToCart and trackRemoveFromCart require product_id, quantity, and price; they also accept product_name and currency.

Checkout

trackCheckoutStart and trackCheckoutComplete accept items plus optional cart_id, total, and currency.

Purchase

trackPurchase requires transaction_id, total_amount, currency, and products. Optional fields include coupon_code, shipping, and tax.

window.upsurge.trackPurchase({
  transaction_id: 'ORDER-10492',
  total_amount: 258.0,
  currency: 'USD',
  products: [
    {
      product_id: 'SKU-TRAIL-123',
      product_name: 'Trail Runner',
      quantity: 2,
      price: 129.0,
      currency: 'USD',
    },
  ],
});

Product-runtime events

Overlay, recommendation, quiz, and chatbot runtimes emit their own impressions, clicks, dismissals, messages, tool outcomes, handoffs, and goal events. Use the public helpers only when you render a custom surface outside those runtimes.

Custom events

Use trackCustom so the required event_name is normalized correctly:

window.upsurge.trackCustom('size_guide_opened', {
  product_id: 'SKU-TRAIL-123',
  placement: 'product_details',
});

Event batches contain 1–100 events. The SDK flushes every 10 seconds by default, when the batch size is reached, when flush() is called, and with a beacon fallback during page unload.