Unicorn Analytics NestJS Client

NestJS клиент для Unicorn Analytics API, предоставляющий возможности отслеживания событий и аналитики для ваших NestJS приложений.

Особенности

• Полная типизация TypeScript
• Автоматическая отправка событий пакетами
• Разделение больших очередей на батчи для предотвращения превышения лимитов API
• Retry механизм с экспоненциальной задержкой
• Поддержка идентификации пользователей
• Интеграция с NestJS DI

Установка

npm install @unicorngo/analytics-nestjs-client

Быстрый старт

1. Импортируйте модуль в ваш app.module.ts

import { Module } from '@nestjs/common';
import { UnicornAnalyticsModule } from '@unicorngo/analytics-nestjs-client';

@Module({
  imports: [
    UnicornAnalyticsModule.forRoot({
      apiEndpoint: 'https://api.analytics.unicorngo.ru/api',
      source: 'backend',    // Опционально: источник событий (добавляется в properties каждого события)
      flushInterval: 10000, // Опционально: интервал авто-отправки в мс (по умолчанию: 10000)
      maxBatchSize: 100,    // Опционально: макс. событий в пакете (по умолчанию: 100)
      debug: true,          // Опционально: включить отладочные логи (по умолчанию: false)
    }),
  ],
})
export class AppModule {}

2. Используйте сервис в ваших контроллерах или сервисах

import { Injectable } from '@nestjs/common';
import { UnicornAnalyticsService } from '@unicorngo/analytics-nestjs-client';

@Injectable()
export class UserService {
  constructor(private readonly analytics: UnicornAnalyticsService) {}

  async createUser(userData: any) {
    // Ваша логика создания пользователя
    const user = await this.userRepository.save(userData);

    // Отслеживание события
    this.analytics.track('User Created', user.id, {
      email: user.email,
      plan: user.plan,
    });

    // Идентификация пользователя
    this.analytics.identify(user.id, {
      email: user.email,
      name: user.name,
      createdAt: user.createdAt,
    });

    return user;
  }

  async viewProduct(productId: string, userId: string) {
    // Отслеживание события просмотра продукта
    this.analytics.track('Product Viewed', userId, {
      productId,
      timestamp: new Date().toISOString(),
    });
  }
}

Параметры конфигурации

interface UnicornAnalyticsConfig {
  apiEndpoint: string;       // Обязательно: Endpoint Unicorn Analytics API
  source?: string;           // Опционально: Источник событий (добавляется в properties всех событий)
  flushInterval?: number;    // Опционально: Интервал авто-отправки в мс (по умолчанию: 10000)
  maxBatchSize?: number;     // Опционально: Макс. событий в пакете (по умолчанию: 100)
  debug?: boolean;           // Опционально: Включить отладочные логи (по умолчанию: false)
  retryAttempts?: number;    // Опционально: Количество попыток повтора (по умолчанию: 3)
  retryDelay?: number;       // Опционально: Базовая задержка повтора в мс (по умолчанию: 1000)
}

Асинхронная конфигурация

Для динамической конфигурации (например, из ConfigService):

import { Module } from '@nestjs/common';
import { ConfigModule, ConfigService } from '@nestjs/config';
import { UnicornAnalyticsModule } from '@unicorngo/analytics-nestjs-client';

@Module({
  imports: [
    ConfigModule.forRoot(),
    UnicornAnalyticsModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        apiEndpoint: configService.get('UNICORN_ANALYTICS_API_ENDPOINT'),
        source: configService.get('UNICORN_ANALYTICS_SOURCE', 'backend'),
        flushInterval: configService.get('UNICORN_ANALYTICS_FLUSH_INTERVAL', 10000),
        debug: configService.get('NODE_ENV') === 'development',
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

API Методы

track(eventName: string, distinctId: string, properties?: EventProperties)

Отслеживание пользовательских событий с обязательным идентификатором пользователя и опциональными свойствами.

this.analytics.track('Purchase Completed', 'user-123', {
  orderId: 'ORD-123',
  amount: 99.99,
  currency: 'USD',
  items: ['item1', 'item2'],
});

identify(distinctId: string, properties?: UserProperties)

Идентификация пользователей и установка их свойств. Создает событие с именем 'identify', где все свойства добавляются с префиксом 'identify_'.

this.analytics.identify('user-123', {
  email: '[email protected]',
  name: 'Иван Иванов',
  plan: 'premium',
  signupDate: '2024-01-15',
});
// Создаст событие: { eventName: 'identify', properties: { identify_email: '[email protected]', ... } }

flush()

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

await this.analytics.flush();

reset()

Очистка очереди событий.

this.analytics.reset();

Структура события

interface AnalyticsEvent {
  eventId: string;      // UUID события
  distinctId: string;   // Идентификатор пользователя
  eventName: string;    // Название события
  properties: Record<string, any>; // Свойства события
  createdAt: Date;      // Время создания
}

Технические детали

• Эндпоинт: События отправляются на /api/events
• Пакетная отправка: События группируются и отправляются пакетами
• Разделение на батчи: При превышении maxBatchSize очередь автоматически разделяется на несколько батчей
• UUID: Каждое событие получает уникальный UUID идентификатор
• Source: Опциональное поле source добавляется во все события при настройке
• Автоматическая отправка: События отправляются автоматически при достижении maxBatchSize или по таймеру flushInterval

Лицензия

MIT