Paquetes

Dos puntos de entrada sobre una implementación.

Publicar una segunda implementación de captura para el servidor significaría dos copias de la gestión de cookies y la lectura del consentimiento que se irían desalineando, lo que se manifestaría como dos comportamientos bajo un mismo nombre y sin forma de saber desde un dashboard cuál produjo una fila. El punto de entrada del servidor no captura nada: envía eventos que ya conoces, usando el mismo formato de datos que usa el navegador, hacia la misma ruta de análisis en el collector.

Por qué existe la mitad del servidor

El navegador no puede ver un webhook, un job en segundo plano o un pago confirmado por un proveedor tres segundos después de que el cliente cerró la pestaña. Esos son los eventos que más valen, porque llevan el ingreso que realmente se asentó en lugar del total que estaba en el carrito.

import { track } from '@vibiz/analytics/node';

await track({
  orgId: process.env.VIBIZ_ID,
  event: 'purchase',
  visitorId,                      // persisted with the order at checkout
  properties: { value: 49.9, currency: 'EUR', order_id: order.id },
});

Di quién es el visitante, no quién eres tú

Una llamada desde el servidor nos llega desde tu datacentre. Leída a partir de la petición, la dirección, el user agent y el país describen tu infraestructura y no a tu cliente, y se le entrega a Meta un robot en Fráncfort como la persona que convirtió. Envía en su lugar los datos propios del visitante, capturados en la petición que vino de su navegador:

await track({
  orgId: process.env.VIBIZ_ID,
  event: 'purchase',
  visitorId,
  url: landingUrl,          // where the UTMs and the click id are read from
  clientIp, clientUserAgent, clientCountry,
  properties: { value: 49.9, currency: 'EUR', order_id: order.id },
});

url merece su propia frase, porque nada más la sustituye. No recibimos parámetros UTM, los extraemos de esa cadena, junto con fbclid, gclid y ttclid. Un evento de servidor enviado sin ella no lleva campaña ni click id, es decir, no es atribuible a ninguna publicidad. Envía la landing URL; las conversiones posteriores pueden omitirla, porque la adquisición ya está registrada para el visitante.

Captura los tres campos del cliente cuando el navegador está delante de ti y consérvalos junto con el pedido. Para cuando se dispare un webhook de pago, la petición que tienes en tus manos pertenece a Stripe.

visitorId es lo que une una conversión del lado servidor con la visita que la produjo y, por tanto, con el clic del anuncio. Es legible a partir de la cookie vbz_vid: guárdalo junto con el pedido. Es la diferencia entre una compra atribuida a una campaña y otra atribuida a nadie.

Envía el mismo order_id desde ambas mitades. Sin él, una compra registrada en ambos lugares se cuenta dos veces, lo cual es peor que no rastrearla en ninguno de los dos: las cifras se ven mejores y la optimización se entrena con ingresos que no existen.

Nunca lanza excepciones

track devuelve un resultado en lugar de lanzar. Se ejecuta dentro de webhooks de pago y confirmaciones de pedido, y una llamada de tracking que tumbe un handler de checkout es un resultado mucho peor que un evento ausente.

Tampoco hay reintentos por debajo, a propósito. Un llamador dentro de un webhook ya tiene una política de reintentos impuesta por el proveedor, y una segunda por debajo produce eventos duplicados en cada reentrega.

El protocolo de red es solo-append

Una versión publicada hoy seguirá enviando el mismo sobre en tres años. Se pueden añadir campos, ya que los emisores antiguos simplemente los omiten, pero nunca se renombran, se cambian de tipo ni se les da un nuevo significado. Cambiar la forma implica una versión nueva y una migración que levanta la anterior, nunca una edición in situ.

Por eso sid, d, el y pii son opcionales: cada uno se añadió después de que se enviara el primer cliente, y ese cliente sigue funcionando.