@unicorn/unicorn-analytics-browser-client

Браузерный клиент для отправки аналитических событий. Работает только в браузере.

Установка

npm install @unicorn/unicorn-analytics-browser-client
# или
yarn add @unicorn/unicorn-analytics-browser-client

Использование

import { UnicornAnalytics } from '@unicorn/unicorn-analytics-browser-client';

// Создание клиента
const analytics = new UnicornAnalytics({
  apiEndpoint: 'http://localhost:3001',
  debug: true, // Включить отладочные сообщения
});

// Отправка события
analytics.track('button_clicked', {
  button_name: 'Subscribe',
  page: 'home',
});

// Отслеживание просмотра страницы
analytics.pageView(); // Использует текущий URL
// или с кастомным URL
analytics.pageView('https://example.com/page?utm_source=email');

// Идентификация пользователя
analytics.identify('user-123');

// Идентификация с дополнительными свойствами
analytics.identify('user-123', {
  email: '[email protected]',
  name: 'John Doe',
  plan: 'premium'
});

// Получить текущий distinctId (ID пользователя)
const distinctId = analytics.getDistinctId();

// Получить текущий sessionId (ID сессии)
const sessionId = analytics.getSessionId();

// Принудительная отправка событий
await analytics.flush();

// Сброс состояния
analytics.reset();

API

Конфигурация

interface UnicornAnalyticsConfig {
  apiEndpoint: string;        // URL API сервера
  flushInterval?: number;    // Интервал автоматической отправки (мс, по умолчанию 10000)
  maxBatchSize?: number;     // Максимальный размер батча (по умолчанию 100)
  debug?: boolean;           // Режим отладки
  source?: string;           // Источник событий (необязательно)
  deviceUUID?: string;       // DeviceUUID получаемый от Mindbox (необязательно)
}

Методы

• track(eventName: string, properties?: Record<string, any>) - Отправить событие
• pageView(url?: string) - Отслеживать просмотр страницы. Автоматически парсит query параметры в свойства pageview_query_*
• identify(distinctId: string, properties?: Record<string, any>) - Идентифицировать пользователя. При вызове автоматически отправляется событие identify со свойствами с префиксом identify_*
• flush(): Promise<void> - Принудительно отправить накопленные события
• reset() - Сбросить состояние клиента и очистить ID пользователя
• getDistinctId(): string | null - Вернуть текущий distinctId. Если пользователь ещё не идентифицирован, возвращает null.
• getSessionId(): string - Вернуть текущий sessionId (идентификатор сессии). Генерируется при создании клиента и обновляется при reset().

Особенности

• Только для браузера - использует браузерные API (localStorage, window events)
• Автоматическая генерация и сохранение distinctId в localStorage
• Генерация sessionId для отслеживания сессий
• Батчинг событий для оптимизации производительности
• Автоматическая отправка событий при закрытии страницы (beforeunload)
• Повторная отправка при ошибках
• TypeScript поддержка из коробки
• UMD и ESM форматы для различных способов подключения

Пример интеграции

<!-- В HTML -->
<script src="path/to/unicorn-analytics.js"></script>
<script>
  const analytics = new UnicornAnalytics({
    apiEndpoint: 'https://analytics.example.com'
  });
  
  // Отслеживание кликов
  document.getElementById('subscribe-btn').addEventListener('click', () => {
    analytics.track('subscribe_clicked', {
      plan: 'premium'
    });
  });
  
  // Получение sessionId
  console.log('Current sessionId:', analytics.getSessionId());
</script>

// В JavaScript приложении
import { UnicornAnalytics } from '@unicorn/unicorn-analytics-browser-client';

const analytics = new UnicornAnalytics({
  apiEndpoint: process.env.ANALYTICS_API_URL,
  debug: process.env.NODE_ENV === 'development'
});

// Отслеживание навигации
window.addEventListener('popstate', () => {
  analytics.pageView(); // Автоматически парсит текущий URL и его параметры
});

// Отслеживание ошибок
window.addEventListener('error', (event) => {
  analytics.track('error', {
    message: event.message,
    source: event.filename,
    line: event.lineno
  });
});

Совместимость

Клиент требует следующие браузерные API:

• localStorage для хранения ID пользователя
• fetch для отправки запросов
• URL и URLSearchParams для парсинга URL
• window.addEventListener для обработки событий

Поддерживаются все современные браузеры (Chrome, Firefox, Safari, Edge).

Лицензия

MIT