Bridge de tracking GTM

Cuando los eventos de checkout y side-cart no llegan a Dialog automáticamente (todo lo que no es Shopify ni Prestashop), los conectas vía el bridge window.DialogTracking. Es la vía más común porque casi todo el mundo ya tiene GTM tagueando sus eventos de carrito y checkout.

Qué hace el bridge

Cuando el widget Dialog está cargado en una página, expone:

window.DialogTracking.track(eventName, payload)

Llamas a esto desde tags GTM para reenviar un evento add_to_cart o purchase a Dialog. Cualquier otro nombre se ignora — solo se aceptan estos dos.

Prerrequisitos

El script del widget Dialog debe estar cargado en la página donde llames window.DialogTracking.track(...). Sobre todo, asegúrate de que el script del widget se dispara en tu página de confirmación de pedido — esa es la razón #1 por la que window.DialogTracking es undefined cuando tu tag purchase se dispara.
Tienes acceso de edición a tu contenedor GTM.
Los eventos que quieres reenviar ya existen en GTM (típicamente vía pushes a dataLayer desde tu sitio o un setup GA4 / Ecommerce).

Eventos soportados

Solo estos dos:

add_to_cart
purchase

Spec del payload

Campos comunes

Campo	Tipo	Descripción
`value`	number	Valor total (subtotal del carrito para `add_to_cart`, total del pedido para `purchase`).
`currency`	string	Código ISO de moneda, ej. `"EUR"`, `"USD"`.
`items`	array (opcional)	Items afectados — ver whitelist abajo.

`purchase` añade

Campo	Tipo	Descripción
`transaction_id`	string	ID único de transacción o pedido.

Campos de item permitidos

Whitelist (otros campos se descartan):

item_id
item_name
price
quantity
item_brand
item_category
item_variant
index
coupon
discount

Implementación GTM

Tag 1: reenviar `purchase`

En GTM, crea un tag HTML personalizado llamado Dialog: forward purchase.

Trigger: tu trigger purchase existente (típicamente en la página de confirmación).

<script>
  if (window.DialogTracking && typeof window.DialogTracking.track === 'function') {
    window.DialogTracking.track('purchase', {
      transaction_id: 'TRANSACTION_ID',
      value: VALUE,
      currency: 'CURRENCY',
      items: ITEMS
    });
  }
</script>

Reemplaza TRANSACTION_ID, VALUE, CURRENCY, ITEMS con tus variables GTM. items es opcional.

Tag 2: reenviar `add_to_cart`

<script>
  if (window.DialogTracking && typeof window.DialogTracking.track === 'function') {
    window.DialogTracking.track('add_to_cart', {
      value: VALUE,
      currency: 'CURRENCY',
      items: ITEMS
    });
  }
</script>

El guard if (window.DialogTracking) es obligatorio — ver la race condition abajo.

Evitar el doble conteo del añadir al carrito desde el asistente

Si reenvías add_to_cart con este bridge y el widget Dialog está instalado vía GTM, un añadir al carrito disparado desde el asistente se cuenta dos veces en user_added_to_cart: una vez por Dialog mismo (sabe que el asistente añadió el artículo) y otra por tu evento GA reenviado. El evento específico user_added_to_cart_from_assistant no se ve afectado.

Para mantener un único user_added_to_cart por añadir al carrito desde el asistente, indícale al widget que ya reenvías add_to_cart de GA añadiendo bridgesGaAddToCart=true al script de instalación:

<script src="https://cdn.askdialog.com/assets/dialog-instant.js?productId={{Dialog Product ID}}&apiKey=YOUR_API_KEY&target=YOUR_CSS_SELECTOR&position=afterend&bridgesGaAddToCart=true"></script>

Dialog deja entonces de emitir su propio user_added_to_cart para las acciones del asistente, dejando tu evento GA reenviado como única fuente.

Race condition: el gotcha clásico

window.DialogTracking se establece por el script del widget Dialog después de que se haya cargado e inicializado. Si tu tag GTM se dispara antes de que el script del widget haya corrido, window.DialogTracking es undefined y la llamada no hace nada — el evento se pierde silenciosamente.

Los dos patterns seguros:

Mantén siempre el guard if (window.DialogTracking). En el peor caso, un evento se pierde; en el mejor, tu tag nunca throw.
Secuencia tus triggers. En una página de confirmación, dispara tu tag purchase después de que el script del widget haya cargado — ej. trigger en DOMContentLoaded o un evento custom que pushes al dataLayer cuando el widget dice estar listo.

Concretamente: si tu tag purchase se dispara en Page View - DOM Ready y el widget carga en async, vas a perder purchases. Cambia a Window Loaded o envuelve la llamada en un retry pequeño:

<script>
  (function tryTrack(attempts) {
    if (window.DialogTracking && typeof window.DialogTracking.track === 'function') {
      window.DialogTracking.track('purchase', {
        transaction_id: 'TRANSACTION_ID',
        value: VALUE,
        currency: 'CURRENCY',
        items: ITEMS
      });
      return;
    }
    if (attempts <= 0) return;
    setTimeout(function () { tryTrack(attempts - 1); }, 200);
  })(20); // hasta 4 segundos de polling
</script>

Este es el pattern que recomendamos en páginas de confirmación donde no te puedes permitir perder el evento purchase.

Lo que tienes que tener en la página

Para que el bridge exista, el script del widget Dialog debe correr en la página donde llamas a window.DialogTracking.track(...). El tag exacto depende de tu instalación:

Instalación GTM → el mismo <script src="https://cdn.askdialog.com/assets/dialog-instant.js?..."></script> que configuraste en Instalar vía Google Tag Manager. Asegúrate de que su trigger se dispare también en tu página de confirmación, no solo en las páginas de producto.
Instalación SDK / React / Vue → el SDK está bundleado con tu frontend, así que el bridge está expuesto donde sea que corra tu código storefront. Solo verifica que tu página de confirmación está renderizada por el mismo frontend (típico SPA) — una página de confirmación server-rendered fuera de tu SPA no tendrá el SDK cargado.

Checklist QA

Abre tu sitio con el widget Dialog cargado.
En la consola del navegador, tipea window.DialogTracking. Debe estar definido.
Dispara un add-to-cart. Confirma en el dashboard Dialog que el evento side-cart se dispara.
Dispara un purchase. Confirma que el evento checkout se dispara.

Troubleshooting

Síntoma	Causa probable	Fix
`window.DialogTracking` es `undefined`	Script del widget no cargado en esa página, o no ha terminado de inicializar	Verifica que el tag del script del widget está presente y se dispara en esta página; usa el pattern de retry de arriba
El tag purchase se dispara en la página de confirmación pero Dialog no reporta nada	Race condition — el tag se dispara antes de que el script del widget termine de cargar	Mueve el trigger a `Window Loaded`, o envuelve la llamada en el bucle de retry de arriba
`value` o `currency` incorrectos	Las variables GTM resuelven demasiado tarde	Mueve el tag a un trigger posterior o lee desde un push de dataLayer estable

Sincronizar la variante PDP seleccionada

En páginas de producto donde el usuario puede cambiar de variante sin recargar (swatches de color/talla, selectores AJAX), Dialog no sabe qué variante está seleccionada a menos que se lo digas. El widget expone un método público para eso:

window.dialog?.setVariant('variant-id');

Llámalo desde el tag GTM que escucha tu evento dataLayer de cambio de variante, o desde cualquier listener del storefront que ya tengas en el selector de variante. El guard ?. cubre el caso donde el widget aún no ha cargado — misma race condition que el bridge.

Cuando el usuario elige una variante desde el asistente, Dialog emite un evento dialog:variant-changed en window. Escúchalo si quieres reflejar esa selección en tu UI del storefront o en tu capa analítica:

window.addEventListener('dialog:variant-changed', (event) => {
  console.log('Variante Dialog seleccionada:', event.detail.variantId);
});

Conectar ambas direcciones mantiene las recomendaciones, las sugerencias y la atribución del side-cart fijadas en la variante que el usuario está mirando de verdad.

Qué sigue

Vista general del tracking — automático vs manual según vía de instalación.
Tracking SDK personalizado — la alternativa cuando prefieres llamar a los métodos del SDK directamente desde tu código frontend.