tracker

Tracker SDK es una librería de análisis web de tamaño mínimo diseñada para una integración rápida en aplicaciones web modernas, especialmente aquellas generadas por herramientas asistidas por IA como Vibe Coding. Se enfoca en la simplicidad: una sola llamada `init` configura el punto final del colector, después del cual las páginas vistas se registran automáticamente y los eventos personalizados pueden enviarse con `track(eventName, data)`. **Capacidades principales** - **Inicio sin configuración** – Agregar una etiqueta de script o una importación de npm es suficiente para comenzar a recolectar datos. - **Detección automática de pageviews** – El SDK escucha eventos de navegación y envía un payload de `pageview` sin código adicional. - **Tracking de eventos personalizados** – Los desarrolladores pueden registrar cualquier interacción llamando a `track` con un nombre y un payload opcional. - **Fingerprinting de dispositivo** – Una huella basada en canvas identifica de forma única a los visitantes respetando la privacidad. - **Cola offline** – Los eventos que no se pueden enviar se almacenan en el almacenamiento local y se reintentan posteriormente, minimizando la pérdida de datos. - **Gestión de sesiones** – Las sesiones se crean automáticamente y expiran tras un tiempo configurabilidad (por defecto 30 minutos). - **Agrupación configurable** – Los eventos se agrupan en una sola solicitud para reducir la sobrecarga de red. **Instalación** - **CDN** – Incluye el paquete UMD directamente en HTML y llama a `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`. - **npm** – `npm install @weavefox/tracker` luego importa las funciones: `import { init, track, setUserId } from '@weavefox/tracker';`. **API pública** | Método | Propósito | |--------|---------| | `init(config)` | Inicializa el SDK con endpoint, appId y banderas opcionales. | | `track(eventName, data)` | Envía un evento personalizado. | | `trackPageview(data)` | Registra manualmente una página vista (activado por defecto). | | `setUserId(userId)` | Asocia un usuario autenticado con eventos posteriores. | | `getFingerprint()` | Recupera la huella del dispositivo generada. | | `flush()` | Despacha inmediatamente cualquier evento en cola. | **Opciones de configuración** ```javascript WFTK.init({ endpoint: 'requerido', // URL del servicio colector appId: 'opcional', // Identificador de la aplicación autoPageview: true, // Rastrear páginas vistas automáticamente debug: false, // Habilitar depuración en consola enableQueue: true, // Almacenar eventos offline cuando fallla la red sessionTimeout: 1800000, // Tiempo de espera de sesión inactiva en ms (por defecto 30 min) maxEventsPerSession: 1000 // Límite superior de eventos por sesión }); ``` **Formato de payload** – Cada solicitud contiene un cuerpo JSON con un `appId` opcional y un array `events`. Cada evento incluye un nombre `event` obligatorio, `timestamp`, `nonce` (para deduplicación), `fingerprint`, y un objeto `data` con contexto recopilado por el sistema (URL, título, información del dispositivo, etc.). Los campos definidos por el usuario pertenecen al subobjeto `biz`, manteniendo separados los datos analíticos y de negocio. **Consideraciones del lado del servidor** - **Validación de timestamp** – Rechazar eventos anteriores a 5 minutos para prevenir ataques de replay. - **Deduplicación de nonce** – Almacenar nonces (por ejemplo, en Redis) con un TTL de 24 horas para garantizar la idempotencia. - **Limitación de tasa** – Aplicar límites por IP y por fingerprint para frenar el abuso. - **Identificación de aplicación** – Preferir un `appId` explícito en el payload; usar el host `Referer` de la solicitud como alternativa. - **Ejemplo de handler Express** – El README proporciona un fragmento conciso de Node.js que valida timestamps, verifica nonces y persiste eventos. **Licencia** – Distribuido bajo la licencia MIT, permitiendo uso sin restricciones en proyectos de código abierto y comerciales. En general, Tracker SDK ofrece una solución sencilla y consciente de la privacidad para desarrolladores que necesitan análisis confiables del lado del cliente sin la sobrecarga de plataformas pesadas.