Tracking SDK personalizado

Cuando Dialog está instalado vía el SDK, los componentes React o los componentes Vue, los eventos dentro del asistente se trackean automáticamente. Los eventos side-cart y checkout que pasan fuera del asistente no: los conectas llamando a dos métodos del SDK.

Usuarios React y Vue: esto les concierne

Los paquetes de componentes React y Vue envuelven el mismo SDK. Aún así tienes que llamar client.registerAddToCartEvent y client.registerSubmitCheckoutEvent desde tu código storefront: usar los componentes no los auto-trackea.

Si prefieres no llamar a métodos del SDK desde tu código, la alternativa es el bridge de tracking GTM: si tu tagging GTM existente ya empuja eventos add_to_cart y purchase, reenvíalos desde GTM en su lugar.

Lo que conectas tú mismo

Dos eventos:

• user_added_to_cart: cuando el usuario añade un producto al carrito fuera del asistente (ej. desde tus botones de PDP).
• user_submitted_checkout: cuando el usuario completa el checkout, haya usado Dialog o no.

Ambos son necesarios para que el dashboard calcule tu baseline real de add-to-cart rate, el checkout / conversion rate y la atribución de revenue. Ver por qué importa.

registerAddToCartEvent

Llámalo desde donde tu sitio añade un producto al carrito: típicamente el click handler de tu botón “Add to cart”, o justo después de que tu API de mutación de carrito devuelva éxito.

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

Parámetros

Campo	Tipo	Requerido	Descripción
productId	string	Sí	El ID del producto, matcheando tu catálogo.
quantity	number	Sí	Número de unidades añadidas.
currency	string	No	Código ISO de moneda, ej. 'EUR'.
variantId	string	No	ID de variante si aplica.
price	number	No	Precio unitario.

registerSubmitCheckoutEvent

Llámalo una vez por pedido completado, desde tu página de confirmación de pedido (o donde sepas que el checkout tuvo éxito). Pasa el total del pedido en orderValue: es lo que lee el KPI «Ingresos generados» del dashboard.

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 },
  ],
})

Parámetros

Campo	Tipo	Requerido	Descripción
orderValue	number	Sí	El total del pedido. Es a partir de esto que se calculan los ingresos.
currency	string	No	Código de moneda ISO, ej. 'EUR'.
transactionId	string	No	ID del pedido. Se usa para deduplicar si la página de confirmación se recarga. Muy recomendado.
items	array	No	Líneas del pedido, solo para atribución por producto. Los ingresos nunca se suman desde estas líneas: vienen de orderValue.

Llámalo una vez por pedido, con el total

No llames a este método una vez por línea del carrito, y no pases el price de una sola línea como importe. Sin un total en orderValue, el dashboard reporta 0 ingresos para tu tienda.

onAssistantEvent: reenviar a tus propios analytics

Suscríbete a los eventos emitidos por el asistente y reenvíalos donde quieras: GA4, Segment, Mixpanel, tu 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
  }
})

// Más tarde, en unmount / cambio de ruta SPA
unsubscribe()

Tipos de eventos

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

Forma del payload

interface AssistantEvent {
  type: string
  payload: {
    date: string        // timestamp ISO
    locale: string      // locale actual
    url: string         // URL de la página actual
    userId?: string     // presente cuando se conoce
    productId?: string  // presente para eventos scopeados a producto
    variantId?: string  // presente para eventos scopeados a variante
  }
}

Ejemplo de extremo a extremo

Un setup mínimo, aplicable a React, Vue o vanilla:

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

const client = new Dialog({
  apiKey: 'YOUR_PUBLIC_API_KEY',
  locale: 'es',
  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()
    },
  },
})

// Add-to-cart side-cart (botón fuera del asistente)
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',
  })
})

// Página de éxito de checkout: una vez por pedido, con el total
client.registerSubmitCheckoutEvent({
  orderValue: 59.98,
  currency: 'EUR',
  transactionId: orderId,
  items: [{ productId, variantId, quantity: 1, price: 59.98 }],
})

Qué sigue

• Vista general del tracking: automático vs manual según vía de instalación.
• Bridge de tracking GTM: vía alternativa si tu GTM ya dispara estos eventos.
• Referencia del SDK: el resto de la API del SDK.