visitor-analytics

Visitor Analytics SDK is a TypeScript analytics library designed for web applications. It works with any front‑end framework such as React, Vue, Svelte, Solid, Astro, as well as vanilla JavaScript. The SDK emphasizes privacy: it never collects personally identifiable information and all data is anonymized. Key features include: - Framework‑agnostic operation with dedicated integration packages for major frameworks. - Modular, plugin‑based architecture allowing custom collectors, storage adapters and plugins. - Type‑safe API with strict TypeScript definitions and no any types. - Tree‑shakable ESM modules so only needed parts are bundled. - Zero runtime dependencies and optimized performance using passive listeners, requestIdleCallback, debounced handlers and batched DOM reads. - Offline support with a queue that syncs when the network is available, plus exponential backoff retries and sendBeacon fallback for page unload. - Configurable options such as batch size, flush interval, retry limits, compression, deduplication, session timeout and custom data fields. The SDK provides a core createAnalytics function that returns an analytics instance. The instance offers methods to start, stop, flush, sync, retry failed uploads, add or remove collectors, install plugins, query stored records, export data, manually track route changes, subscribe to events and destroy the instance. Collectors gather a wide range of data: browser name and version, device OS and platform, screen dimensions, performance metrics (navigation timing, paint timing, LCP, CLS, INP), environment details (timezone, language, color scheme), feature support (WebGL, WebGPU, WASM, Service Worker) and user interactions (session duration, scroll depth, click count, route changes, UTM parameters). All collectors are optional and can be extended with custom implementations. Storage adapters are provided for in‑memory, localStorage and IndexedDB, with the ability to plug in custom backends such as a Redis adapter. The uploader batches records, handles retries with exponential backoff, deduplicates batches and can compress payloads when the browser supports CompressionStream. Integration examples cover React (AnalyticsProvider, useAnalytics, usePageView), Vue (createAnalyticsPlugin, useVueAnalytics), Svelte (createAnalyticsStore), SolidJS (AnalyticsProvider, createAnalyticsHook), Astro and plain JavaScript. Each integration demonstrates how to initialize the SDK, access collected data and trigger manual uploads. The SDK includes a plugin system. Plugins can register additional collectors or modify behavior during installation and clean up on uninstall. An example AB‑test plugin adds the current experiment variant to every record. Privacy guarantees are explicit: no names, emails, passwords, cookies contents, form inputs, exact IP addresses, GPS coordinates, keystrokes, click coordinates or any persistent fingerprint identifiers are ever collected. Session identifiers are random UUIDs generated per instance and are not persisted across sessions. Known limitations include activity‑based session timeout, non‑atomic writes when using LocalStorage in multi‑tab scenarios (IndexedDB is recommended), and optional gzip compression requiring recent browser support. Performance optimizations consist of passive event listeners, requestIdleCallback for heavy work, debounced scroll and resize handling, lazy collector initialization, batched DOM reads via requestAnimationFrame and reliable delivery using navigator.sendBeacon on unload. The SDK is released under the MIT license.