tracker

Tracker SDK — это библиотека веб-аналитики минимального размера, разработанная для быстрой интеграции в современные веб-приложения, особенно те, что создаются с помощью AI-инструментов вроде Vibe Coding. Акцент на простоте: один вызов `init` настраивает коллектор, после чего просмотры страниц записываются автоматически, а пользовательские события отправляются через `track(eventName, data)`. **Ключевые возможности** - **Запуск без конфигурации** — достаточно добавить один тег script или выполнить npm-импорт для начала сбора данных. - **Автоматическое обнаружение pageview** — SDK отслеживает события навигации и отправляет пейлоад `pageview` без дополнительного кода. - **Трекинг пользовательских событий** — разработчики могут регистрировать любые взаимодействия вызовом `track` с именем и необязательным пейлоадом. - **Fingerprint устройств** — canvas-based отпечаток однозначно идентифицирует посетителей при соблюдении конфиденциальности. - **Офлайн-очередь** — несохранённые события хранятся в local storage и повторяются позже, минимизируя потерю данных. - **Управление сессиями** — сессии создаются автоматически и истекают после настраиваемого таймаута (по умолчанию 30 минут). - **Настраиваемый батчинг** — события группируются в один запрос для снижения сетевой нагрузки. **Установка** - **CDN** — подключите UMD-сборку напрямую в HTML и вызовите `WFTK.init({ endpoint: 'https://your-api.com/api/v1/collect/event', debug: true })`. - **npm** — `npm install @weavefox/tracker`, затем импортируйте функции: `import { init, track, setUserId } from '@weavefox/tracker';`. **Публичный API** | Метод | Назначение | |--------|---------| | `init(config)` | Инициализация SDK с endpoint, appId и необязательными флагами. | | `track(eventName, data)` | Отправка пользовательского события. | | `trackPageview(data)` | Ручная запись просмотра страницы (по умолчанию включено авто). | | `setUserId(userId)` | Связь залогиненного пользователя с последующими событиями. | | `getFingerprint()` | Получение сгенерированного отпечатка устройства. | | `flush()` | Немедленная отправка всех событий из очереди. | **Параметры конфигурации** ```javascript WFTK.init({ endpoint: 'required', // URL сервиса-коллектора appId: 'optional', // Идентификатор приложения autoPageview: true, // Автоматический трекинг pageviews debug: false, // Включение консоли отладки enableQueue: true, // Сохранять события офлайн при сбое сети sessionTimeout: 1800000, // Таймаут неактивности сессии в мс (по умолч. 30 мин) maxEventsPerSession: 1000 // Верхняя граница событий на сессию }); ``` **Формат пейлоада** — каждый запрос содержит JSON с опциональным `appId` и массивом `events`. Каждое событие включает обязательные поля: `event` (имя), `timestamp`, `nonce` (для дедупликации), `fingerprint` и объект `data` с системно-собираемым контекстом (URL, заголовок, информация об устройстве и т.д.). Пользовательские поля размещаются в под-объекте `biz`, разделяя аналитические и бизнес-данные. **Рекомендации для серверной стороны** - **Проверка timestamp** — отклонять события старше 5 минут во избежание replay-атак. - **Дедупликация по nonce** — хранить nonces (например, в Redis) с TTL 24 часа для обеспечения идемпотентности. - **Rate limiting** — применять лимиты на IP и fingerprint для предотвращения злоупотреблений. - **Идентификация приложения** — отдавать приоритет явному `appId` в пейлоаде; при необходимости использовать host из `Referer` запроса. - **Пример Express-хендлера** — README содержит лаконичный сниппет Node.js, который проверяет timestamp, nonces и сохраняет события. **Лицензия** — распространяется под лицензией MIT, позволяющей бессрочное использование как в open-source, так и в коммерческих проектах. Tracker SDK предлагает простое, учитывающее конфиденциальность решение для разработчиков, которым нужна надёжная клиентская аналитика без перегруза тяжёлых платформ.