visitor-analytics

Visitor Analytics SDK es una biblioteca de análisis en TypeScript diseñada para aplicaciones web. Funciona con cualquier framework front-end como React, Vue, Svelte, Solid, Astro, así como con JavaScript puro. La SDK enfatiza la privacidad: nunca recopila información de identificación personal y todos los datos son anónimos. Características principales: - Funcionamiento independiente del framework con paquetes de integración dedicados para los frameworks más importantes. - Arquitectura modular basada en plugins que permite colectores personalizados, adaptadores de almacenamiento y plugins. - API con tipado seguro mediante definiciones estrictas de TypeScript sin usar any. - Módulos ESM compatibles con tree-shaking para que solo se empaqueten las partes necesarias. - Cero dependencias en tiempo de ejecución y rendimiento optimizado usando listeners pasivos, requestIdleCallback, manejadores debounce y lecturas de DOM agrupadas. - Soporte sin conexión mediante una cola que sincroniza cuando hay red disponible, con reintentos por retroceso exponencial y fallback a sendBeacon para descargas de página. - Opciones configurables como tamaño de lote, intervalo de flush, límites de reintento, compresión, deduplicación, tiempo de espera de sesión y campos de datos personalizados. La SDK proporciona una función core createAnalytics que devuelve una instancia de análisis. La instancia ofrece métodos para iniciar, detener, hacer flush, sincronizar, reintentar cargas fallidas, añadir o eliminar colectores, instalar plugins, consultar registros almacenados, exportar datos, rastrear manualmente cambios de ruta, suscribirse a eventos y destruir la instancia. Los colectores recopilan una amplia gama de datos: nombre y versión del navegador, sistema operativo del dispositivo y plataforma, dimensiones de pantalla, métricas de rendimiento (navigation timing, paint timing, LCP, CLS, INP), detalles del entorno (zona horaria, idioma, esquema de color), soporte de características (WebGL, WebGPU, WASM, Service Worker) e interacciones del usuario (duración de sesión, profundidad de desplazamiento, conteo de clics, cambios de ruta, parámetros UTM). Todos los colectores son opcionales y pueden extenderse con implementaciones personalizadas. Se proporcionan adaptadores de almacenamiento para memoria, localStorage e IndexedDB, con capacidad para integrar backends personalizados como un adaptador Redis. El uploader agrupa registros, maneja reintentos con retroceso exponencial, deduplica lotes y puede comprimir payloads cuando el navegador soporta CompressionStream. Ejemplos de integración cubren React (AnalyticsProvider, useAnalytics, usePageView), Vue (createAnalyticsPlugin, useVueAnalytics), Svelte (createAnalyticsStore), SolidJS (AnalyticsProvider, createAnalyticsHook), Astro y JavaScript plano. Cada integración demuestra cómo inicializar la SDK, acceder a los datos recopilados y activar cargas manuales. La SDK incluye un sistema de plugins. Los plugins pueden registrar colectores adicionales o modificar comportamiento durante la instalación y limpiar al desinstalar. Un ejemplo de plugin AB-test añade la variante actual del experimento a cada registro. Garantías de privacidad son explícitas: nunca se recopilan nombres, correos electrónicos, contraseñas, contenidos de cookies, inputs de formularios, direcciones IP exactas, coordenadas GPS, pulsaciones de teclas, coordenadas de clic o cualquier identificador persistente de fingerprint. Los identificadores de sesión son UUID aleatorios generados por instancia y no se persisten entre sesiones. Limitaciones conocidas incluyen tiempo de espera de sesión basado en actividad, escrituras no atómicas al usar LocalStorage en escenarios multi-pestaña (se recomienda IndexedDB) y compresión gzip opcional que requiere soporte reciente del navegador. Optimizaciones de rendimiento consisten en event listeners pasivos, requestIdleCallback para trabajo pesado, manejo debounce de scroll y resize, inicialización perezosa de colectores, lecturas de DOM agrupadas via requestAnimationFrame y entrega confiable usando navigator.sendBeacon al descargar. La SDK se releases bajo la licencia MIT.