Eventos personalizados
Qué se captura automáticamente y cómo añadir tus eventos.
El SDK captura un conjunto de eventos automáticamente. Todo lo demás lo añades con track.
Capturados sin configuración
| Evento | Cuándo | Notas |
|---|---|---|
pageview |
Al cargar y en cada cambio de ruta SPA | Incluye referrer y título |
click |
Cualquier clic | Selector, texto, posición normalizada y absoluta |
scroll |
Al ocultarse la página | Profundidad máxima alcanzada, 0–100 |
rage_click |
3+ clics en <30 px y <1 s | Señal de frustración |
dead_click |
Clic sin mutación del DOM ni navegación | Elemento que parece interactivo y no lo es |
js_error |
window.onerror |
Mensaje, fuente, línea; stack truncado |
sdk_error |
Fallo interno del SDK | No sujeto a consentimiento |
exposure |
Tras aplicar una variante | Una vez por vista de página |
web_vital |
LCP, CLS, INP, FCP, TTFB | Si está activado en el sitio |
engagement |
Tiempo con la página visible e interactuando | Milisegundos |
Por qué scroll se envía al final
Reportar cada scroll generaría cientos de eventos por página. El SDK acumula la profundidad máxima y la envía una vez, al ocultarse la página, con sendBeacon.
Por qué dead_click importa
Un clic que no produce ningún cambio suele significar que el visitante creyó que algo era pulsable. Es una de las señales más directas de fricción de interfaz y no aparece en ninguna métrica agregada.
Eventos personalizados
GrowthLab.track('size_guide_opened', {
product: 'blue-tee',
source: 'product_page',
});
Reglas del nombre
- 1–64 caracteres.
- Solo
[a-zA-Z0-9_.:-].
El nombre se almacena como valor de baja cardinalidad y aparece en los filtros del panel, así que conviene un vocabulario estable. size_guide_opened es útil; abrió la guía de tallas (v2) no.
Reglas de las propiedades
- Objeto plano, máximo 32 claves.
- Claves hasta 64 caracteres, valores hasta 512.
- Valores escalares: cadena, número, booleano o
null. undefinedynullse descartan al almacenar.
Los objetos anidados se rechazan a propósito: hacen crecer el payload sin techo y no se agregan bien. Si necesitas estructura, aplánala:
// En lugar de { product: { id: 'x', price: 1299 } }
GrowthLab.track('view_product', { product_id: 'x', product_price: 1299 });
Eventos de e-commerce
Estos tienen columnas dedicadas, así que se agregan mejor que un track genérico:
GrowthLab.track('add_to_cart', {
product_id: 'tee-blue',
variant_id: '4402',
quantity: 1,
value: 129900, // unidades mínimas
currency: 'MXN',
});
GrowthLab.track('checkout_click', { value: 259800, currency: 'MXN', items: 2 });
Con el adaptador de Shopify activo, add_to_cart y checkout_click se capturan sin escribir código.
Límites del lote
| Límite | Valor |
|---|---|
| Eventos por petición | 100 |
| Tamaño del cuerpo | 512 KB |
| Eventos en cola en el cliente | 500 |
| Intervalo de envío | 3 s |
| Lote máximo por envío | 20 |
Si la cola se llena, se descarta el evento más antiguo. Un colector inalcanzable no debe convertirse en una fuga de memoria en la página del cliente.
Deduplicación
Cada evento lleva un id único generado en el cliente. Se deduplica en el cliente y otra vez en el servidor con una ventana de una hora.
Esto importa porque el SDK reintenta ante fallos de red: el mismo lote llega legítimamente dos veces. Sin deduplicación, una conversión reintentada se contaría dos veces y el revenue quedaría inflado.
Qué no se almacena
- URLs con parámetros no permitidos: solo se conservan UTM, click ids y unos pocos parámetros de navegación. Todo lo demás se elimina, porque las URLs de e-commerce llevan rutinariamente
?email=,?token=o enlaces de acceso. - Fragmentos (
#...), que suelen contener tokens. - Credenciales embebidas en la URL.
- La referencia de
identifyen claro: se hashea con una sal por sitio.
Ver Privacidad.