SDK custom tracking

When Dialog is installed via the SDK, React components, or Vue components, events inside the assistant are tracked automatically. Side-cart and checkout events that happen outside the assistant are not: you wire them by calling two SDK methods.

React and Vue users: this applies to you

The React and Vue component packages wrap the same SDK. You still need to call client.registerAddToCartEvent and client.registerSubmitCheckoutEvent from your storefront code: using the components doesn’t auto-track these.

If you’d rather not call SDK methods from your code, an alternative is the GTM tracking bridge: if your existing GTM tagging already pushes add_to_cart and purchase events, forward them from GTM instead.

What you wire yourself

Two events:

• user_added_to_cart: when the user adds a product to cart outside the assistant (e.g. from your PDP buttons).
• user_submitted_checkout: when the user completes checkout, regardless of whether they used Dialog.

Both are needed for the dashboard to compute your real add-to-cart rate baseline, the checkout / conversion rate, and revenue attribution. See why this matters.

registerAddToCartEvent

Call it wherever your site adds a product to cart: typically the click handler on your “Add to cart” button, or right after your cart-mutation API returns success.

client.registerAddToCartEvent({
  productId: 'product-123',
  quantity: 1,
  currency: 'EUR',
  variantId: 'variant-456',
  price: 29.99,
})

Parameters

Field	Type	Required	Description
productId	string	Yes	The product ID, matching your catalog.
quantity	number	Yes	Number of units added.
currency	string	No	ISO currency code, e.g. 'EUR'.
variantId	string	No	Variant ID if applicable.
price	number	No	Unit price.

registerSubmitCheckoutEvent

Call it once per completed order, from your order-confirmation page (or wherever you know the checkout succeeded). Pass the order total in orderValue: that is what the dashboard’s “Revenue generated” reads.

client.registerSubmitCheckoutEvent({
  orderValue: 59.98,
  currency: 'EUR',
  transactionId: 'order-789',
  items: [
    { productId: 'product-123', quantity: 1, price: 29.99, variantId: 'variant-456' },
    { productId: 'product-456', quantity: 1, price: 29.99 },
  ],
})

Parameters

Field	Type	Required	Description
orderValue	number	Yes	The order total. This is what revenue is computed from.
currency	string	No	ISO currency code, e.g. 'EUR'.
transactionId	string	No	Order ID. Used to de-duplicate if the confirmation page is reloaded. Strongly recommended.
items	array	No	Line items, for product-level attribution only. Revenue is never summed from these: it comes from orderValue.

Call it once per order, with the order total

Do not call this method once per cart line, and do not pass a single line’s price as the amount. Without an order total in orderValue, the dashboard reports 0 revenue for your store.

onAssistantEvent: forward to your own analytics

Subscribe to events emitted by the assistant and forward them anywhere: GA4, Segment, Mixpanel, your warehouse.

const unsubscribe = client.onAssistantEvent((event) => {
  switch (event.type) {
    case 'userAddedToCart':
      analytics.track('dialog_conversion', {
        productId: event.payload.productId,
        variantId: event.payload.variantId,
        timestamp: event.payload.date,
      })
      break

    case 'userSendNegativeFeedback':
      console.warn('Dialog negative feedback at:', event.payload.url)
      break
  }
})

// Later, on unmount / SPA route change
unsubscribe()

Event types

• userOpenedAssistant
• userClosedAssistant
• userSentMessage
• userClickedOnProductCard
• userOpenedRecommendation
• userAddedToCart
• userSendPositiveFeedback
• userSendNegativeFeedback

Payload shape

interface AssistantEvent {
  type: string
  payload: {
    date: string        // ISO timestamp
    locale: string      // current locale
    url: string         // current page URL
    userId?: string     // present when known
    productId?: string  // present for product-scoped events
    variantId?: string  // present for variant-scoped events
  }
}

End-to-end example

A minimal setup, applicable to React, Vue, or vanilla:

import { Dialog } from '@askdialog/dialog-sdk'

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'en',
  callbacks: {
    addToCart: async ({ productId, quantity, variantId, currency }) => {
      await fetch('/api/cart', {
        method: 'POST',
        body: JSON.stringify({ productId, variantId, quantity }),
      })
      window.dispatchEvent(new CustomEvent('cart:updated'))
    },
    getProduct: async (productId, variantId) => {
      const res = await fetch(`/api/products/${productId}?variant=${variantId ?? ''}`)
      return res.json()
    },
  },
})

// Side-cart add-to-cart (button outside the assistant)
document.querySelector('#pdp-add-to-cart')!.addEventListener('click', async () => {
  await addToCart({ productId, variantId, quantity: 1 })
  client.registerAddToCartEvent({
    productId,
    variantId,
    quantity: 1,
    price: 29.99,
    currency: 'EUR',
  })
})

// Checkout success page: once per order, with the order total
client.registerSubmitCheckoutEvent({
  orderValue: 59.98,
  currency: 'EUR',
  transactionId: orderId,
  items: [{ productId, variantId, quantity: 1, price: 59.98 }],
})

Next steps

• Tracking overview: what’s automatic vs manual per install path.
• GTM tracking bridge: alternative path if your GTM already fires these events.
• SDK reference: the rest of the SDK API.