Seguimiento del comercio electrónico

Esta guía explica cómo integrar manualmente el seguimiento e-commerce de Trackboxx en una tienda, tanto si utilizas un sistema personalizado como Shopify, Shopware, Magento u otra plataforma. Para WooCommerce existe un plugin oficial que activa automáticamente todos los eventos descritos aquí.

Lógica básica: ¿Qué significa trackboxx('Purchase', [...])?

Antes de pasar a los distintos eventos, conviene aclarar un punto que, según la experiencia, es el que con más frecuencia se interpreta de forma incorrecta:

Importante: trackboxx('Purchase', [...]) no es un evento individual, sino la llamada genérica para todas las interacciones de comercio electrónico. El primer objeto del array determina qué evento se rastrea mediante su campo type:

• { type: 'ViewProduct' } - Página de detalles del producto
• { type: 'AddToCart' } - Producto añadido a la cesta de la compra
• { type: 'ViewCart' } - Ver la página de la cesta de la compra
• { type: 'order' } - Pedido realizado

El 'Purchase' en la llamada a la función solo indica la categoría de acción «comercio electrónico» y se mantiene igual, tanto si registras una visualización de producto como una adición a la cesta o una compra real.

Los cuatro eventos de comercio electrónico de un vistazo

1. ViewProduct – Página de detalles del producto

Disparador: Al abrir la página de detalles de un producto.
Datos mínimos: Nombre del producto y precio unitario.

<script>
trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 99.90 }
]);
</script>Lenguaje del código: HTML, XML (xml)

Notas:

• price = Precio unitario del producto (numérico, punto como separador decimal).
• Campos adicionales opcionales: sku, category.
• Para las variantes o los paquetes, transmite el nombre completo de la variante con sus atributos (por ejemplo, «Camiseta — roja, L»), para que los informes se agrupen de forma coherente.

2. AddToCart – Producto añadido a la cesta

Activación: Después de completar correctamente la acción «Añadir a la cesta», no con el mero clic.
Datos mínimos: Nombre del producto y precio unitario.

<script>
trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: '%%PRODUCT_NAME%%', price: 19.99 }
]);
</script>Lenguaje del código: HTML, XML (xml)

Notas sobre el momento de activación según el tipo de tienda:

• Tiendas personalizadas y cestas de la compra AJAX: Activa el evento en el callback de éxito de la acción de añadir a la cesta, no en el controlador del clic. Así no se genera un evento de seguimiento si el artículo no llega a la cesta debido a una comprobación de existencias, un error de validación o un fallo de red.
• Tiendas del lado del servidor con redirección: Activar evento una vez en la siguiente página después de una adición exitosa.
• Integraciones sencillas con sólo pulsar un botón: permitidas, pero solo si el clic añade realmente el producto a la cesta, por ejemplo comprobando que el botón esté desactivado para los productos agotados.
• Deduplicación: Enviar AddToCart sólo una vez por acción - sin duplicación para recargar o volver a navegar.

3. ViewCart – Página de la cesta

Disparador: Al abrir la página de la cesta de la compra.
Datos mínimos: Total del carro (amount). Opcional: todos los productos incluidos como objetos separados.

<script>
trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Lenguaje del código: HTML, XML (xml)

Notas:

• amount = importe total de la cesta de la compra. Estándar: Neto (corresponde al comportamiento del plugin oficial de WooCommerce).
• Si tu tienda utiliza precios brutos, también se permiten valores brutos. Lo esencial es la coherencia dentro de un mismo evento: cart.amount y todos los valores de product.price deben calcularse sobre la misma base, todos netos o todos brutos.
• Añade un objeto product independiente por cada línea de la cesta.
• El valor de price por producto corresponde aquí al total de la línea (precio unitario × cantidad); consulta el apartado «Lógica de precios y cantidad».

4. Purchase – Pedido completado (página de agradecimiento)

Disparador: En la página de confirmación del pedido tras el pago - exactamente una vez por pedido.
Datos mínimos: ID del pedido, importe total, todos los productos comprados.

<script>
trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 149.70 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Lenguaje del código: HTML, XML (xml)

Opcional — con cupón: Añade un objeto coupon adicional por cada cupón utilizado.

<script>
trackboxx('Purchase', [
  { type: 'order', id: '12345', total: 149.70 },
  { type: 'coupon', name: 'SUMMER10', discount: 10.00 },
  { type: 'product', name: 'Produkt A', price: 99.90 },
  { type: 'product', name: 'Produkt B', price: 49.80 }
]);
</script>Lenguaje del código: HTML, XML (xml)

Notas:

• El evento Purchase no lleva un marcador de evento inicial como ViewProduct o AddToCart: el objeto order identifica el propio evento.
• order.id = ID de pedido único del sistema de la tienda.
• order.total = valor total del pedido (se recomienda el importe final bruto incluyendo gastos de envío e impuestos, pero debe ser coherente con los valores de product.price).
• product.price = Total del artículo (precio unitario × cantidad), no precio unitario.
• Evita activaciones repetidas al recargar la página, por ejemplo mediante un indicador del lado del servidor o un marcador de sesión.

Lógica de precios y cantidad

Trackboxx no utiliza un campo quantity independiente. Las cantidades se representan implícitamente mediante el precio. Esta regla es obligatoria y debe aplicarse del mismo modo en todas las integraciones:

Ejemplo: Tres artículos idénticos de 19,99 € cada uno en la cesta se envían para ViewCart y Purchase como un único objeto product con price: 59.97, no como tres objetos separados y sin un campo quantity.

Secuencia de objetos en la matriz

Para una integración limpia y coherente, recomendamos la siguiente secuencia de objetos:

1. Marcador de evento u objeto order (ViewProduct / AddToCart / ViewCart / order)
2. Objeto cart (solo para ViewCart)
3. Objetos coupon (solo para Purchase, si hay cupones)
4. Objetos product

Mejores prácticas

• Deduplicación: Envía cada evento una sola vez por acción real: evita el seguimiento duplicado al recargar, volver a la página anterior o reintentar una solicitud AJAX.
• Momento de activación: Activa ViewProduct y ViewCart al cargar la página, AddToCart después de confirmar que se ha añadido el producto a la cesta y Purchase una sola vez en la página de agradecimiento.
• Precios e importes: Transmítelos como Number, no como cadena de texto, con un punto como separador decimal (por ejemplo, 19.99, no "19,99").
• Coherencia: Elige valores netos o brutos para tu tienda y aplica la misma elección a cart.amount, product.price y order.total.
• Protección de datos: No transmitas nunca datos personales: ni direcciones de correo electrónico, ni nombres, ni números de cliente, ni direcciones. Respeta el consentimiento.

Lista de comprobación rápida por sistema de tienda

• WooCommerce: Utiliza el plugin oficial Trackboxx. Activa los cuatro eventos (ViewProduct, AddToCart, ViewCart, Purchase) automáticamente, sin necesidad de integración manual.
• Custom Shops: En el servidor, inserta el nombre del producto, el precio y el total como variables en el script correspondiente.
• Shopify: Inserta los fragmentos de código en las plantillas (product.liquid, cart.liquid, página de agradecimiento tras finalizar la compra). Para AddToCart, utiliza el callback de éxito de AJAX.
• Shopware / Magento: Conecta las llamadas con los eventos o hooks correspondientes del tema o plugin: página de producto, página de la cesta, evento de añadir a la cesta y evento de pedido completado.

Referencia: Variantes mínimas

ViewProduct (mínimo)

trackboxx('Purchase', [
  { type: 'ViewProduct' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Lenguaje del código: JavaScript (javascript)

AddToCart (mínimo)

trackboxx('Purchase', [
  { type: 'AddToCart' },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Lenguaje del código: JavaScript (javascript)

ViewCart (mínimo)

trackboxx('Purchase', [
  { type: 'ViewCart' },
  { type: 'cart', amount: 19.99 }
]);Lenguaje del código: JavaScript (javascript)

Purchase (mínimo)

trackboxx('Purchase', [
  { type: 'order', id: 'ORDER_ID', total: 19.99 },
  { type: 'product', name: 'Product Name 1', price: 19.99 }
]);Lenguaje del código: JavaScript (javascript)

Breve resumen: Las normas más importantes

• trackboxx('Purchase', [...]) es una llamada e-commerce genérica, no un evento.
• El tipo de evento se encuentra en el payload, en el campo type del primer objeto, no en la llamada a la función.
• Activa AddToCart después de añadir correctamente el producto a la cesta, no con el mero clic.
• cart.amount es un valor neto por defecto; se permiten valores brutos, pero deben ser coherentes dentro del evento.
• price corresponde al precio unitario para ViewProduct y AddToCart, y al total de la línea para ViewCart y Purchase.
• No hay un campo quantity independiente: las cantidades se representan mediante el precio.
• El evento Purchase se basa en { type: 'order' }, sin un marcador de evento inicial.
• Transmite los precios como Number, con un punto como separador decimal, nunca como String.
• No transmitas datos personales en el payload.