Smart-Collector Documentation

Что такое Smart-Collector?

Smart-Collector — это интеллектуальная система, которая отслеживает поведение посетителей вашего сайта в режиме реального времени и автоматически определяет наиболее перспективных клиентов с помощью искусственного интеллекта.

Система анализирует действия каждого посетителя, оценивает его готовность к покупке и в нужный момент предлагает помощь через чат-бота, увеличивая конверсию на 30-50%.

Ключевые возможности

🎯 AI-триггеры

Автоматические сообщения в нужный момент на основе анализа поведения

📈 Lead Scoring

Оценка качества лида от 0 до 100 баллов в реальном времени

🔍 Воронка Ханта

Определение этапа осведомленности клиента (5 уровней)

💬 Умный чат

AI-ассистент для общения с посетителями

📊 Dashboard

Визуальная панель для анализа всех посетителей

🤖 MCP AI-анализ

Задавайте вопросы на естественном языке для анализа данных

Как это работает

Посетитель заходит на сайт
Система начинает отслеживать его действия: просмотр страниц, клики, скроллинг, время на сайте
AI анализирует поведение
Каждые 10-30 секунд данные отправляются на анализ. GPT-4o оценивает готовность к покупке и присваивает lead score
Определение этапа воронки
Система определяет на каком этапе находится клиент: от "не знает о проблеме" до "готов к покупке"
Умный триггер
Когда момент подходящий (высокий score, простой > 30 сек), система автоматически предлагает помощь
Диалог с AI-ассистентом
Если посетитель откликается, начинается общение с умным чат-ботом, который отвечает на вопросы и ведет к покупке

Работа с Dashboard

Главная панель

Откройте Dashboard по адресу: https://stats.mbk-chat.ru/dashboard.html

💡 Совет: Dashboard обновляется автоматически каждые 10 секунд. Вы всегда видите актуальную информацию о посетителях.

Фильтры посетителей

В левой панели вы можете фильтровать посетителей по 4 параметрам:

🔥 Температура лида: Горячие (71-100), Теплые (31-70), Холодные (0-30)
📱 Устройство: Mobile, Desktop, Tablet
🎯 Этап воронки: От неосведомленности до готовности к покупке
💬 Статус чата: Начат / Не начат

Карточка посетителя

Кликните на любого посетителя в списке, чтобы увидеть:

Lead Score: Оценка качества лида от 0 до 100
Воронка Ханта: Текущий этап осведомленности
Сигналы покупки: Действия указывающие на готовность
Карта интересов: График по категориям просмотренного контента
История активности: Все события в хронологическом порядке

✅ Приоритет: Сначала обрабатывайте посетителей с высоким Lead Score (выше 70) и активным чатом — это ваши самые перспективные лиды!

🤖 MCP AI-анализ

В верхней части Dashboard находится панель AI-анализа. Здесь вы можете задавать вопросы на обычном русском языке, и система проанализирует данные за вас.

Примеры запросов:

"Найди всех кто просмотрел страницу цен но не начал чат"
"Покажи посетителей с высоким скором"
"Какие общие паттерны у горячих лидов?"
"Кто вернулся на сайт несколько раз?"
"Найди тех кто заполнил форму но не отреагировал на триггер"

Что вы получите:

Список найденных посетителей с возможностью перейти к их карточке
Общие паттерны поведения выявленные AI
Ключевые инсайты о вашей аудитории
Персонализированные рекомендации что делать дальше

💡 Как это работает: Ваш запрос отправляется в GPT-4o вместе с данными о 100 последних посетителях. AI анализирует паттерны и возвращает структурированный ответ.

Расшифровка терминов

Термин	Описание
Lead Score	Оценка качества лида от 0 до 100. Чем выше — тем больше вероятность покупки
AI Trigger	Автоматическое сообщение от системы, предлагающее помощь
Воронка Ханта	5 этапов осведомленности клиента (от незнания проблемы до готовности купить)
Buying Signals	Сигналы готовности к покупке (заполнение формы, клик на CTA, повторный визит)
CTA	Call-to-Action — кнопка призыва к действию (Купить, Заказать, Получить)
Idle Time	Время бездействия — как долго посетитель ничего не делает на странице
MCP	Model Context Protocol — протокол для AI-анализа данных через естественный язык

Лучшие практики

⚠️ Важно: Не спамьте триггерами! Система автоматически контролирует частоту, но вы можете настроить cooldown период в конфигурации.

Как увеличить конверсию:

Отвечайте на сообщения в чате вручную для горячих лидов (score > 80)
Используйте MCP анализ для выявления проблемных мест на сайте
Анализируйте паттерны поведения успешных конверсий
Обновляйте контент на страницах где посетители долго "зависают"
Тестируйте разные варианты триггерных сообщений

Часто задаваемые вопросы

Как часто обновляются данные?

Данные отправляются каждые 10-30 секунд в зависимости от активности посетителя. Dashboard обновляется автоматически каждые 10 секунд.

Можно ли отключить триггеры для конкретных страниц?

Да, в backend можно настроить blacklist страниц где триггеры не будут показываться (например, страница оплаты или личный кабинет).

Как долго хранятся данные о посетителях?

По умолчанию 30 дней. После этого старые записи автоматически удаляются из SQLite индекса (но JSONL логи остаются).

Работает ли система с мобильными устройствами?

Да, трекер полностью адаптирован для мобильных устройств. Система корректно определяет тип устройства и адаптирует поведение триггеров.

Архитектура системы

Smart-Collector построен на современном стеке технологий с микросервисной архитектурой и event-driven подходом для real-time обработки данных.

Технологический стек

Python 3.12 FastAPI OpenAI GPT-4o SQLite JSONL WebSocket Nginx Pusher Playwright Chart.js

Компоненты системы

# Frontend (JavaScript)
tracker.js          # Клиентский трекер поведения
dashboard.html      # Admin UI для анализа
docs.html          # Документация

# Backend (Python/FastAPI)
main.py            # API endpoints (REST + WebSocket)
services.py        # Business logic (AI, Pusher, Logging)
mcp_server.py      # MCP AI-analyzer
db.py              # SQLite index для фильтров
schemas.py         # Pydantic models
page_analyzer.py   # Анализ контента страниц
site_analyzer.py   # Playwright автоанализ структуры

# Infrastructure
nginx              # Reverse proxy + SSL
systemd            # Service management
                    

Data Flow

1. Tracking Pipeline

Browser (tracker.js)
    ↓ POST /api/track (every 10-30s)
FastAPI (main.py)
    ↓ TrackingSnapshot validation (Pydantic)
AIService.calculate_score()
    ↓ HTTP POST → OpenAI GPT-4o
    ↓ Returns lead_score (0-100)
AIService.check_trigger()
    ↓ If score > threshold & cooldown expired
    ↓ HTTP POST → OpenAI GPT-4o
    ↓ Returns {trigger: true, message: "..."}
PusherService.send_trigger()
    ↓ WebSocket → Browser
FileLogger.log_event()
    ↓ Append to JSONL
VisitorIndex.upsert_visitor()
    ↓ SQLite UPDATE/INSERT
                    

2. MCP Analysis Pipeline

Browser (dashboard.html)
    ↓ WebSocket /ws/mcp
MCPAnalyzer.process_query(query)
    ↓ Load 100 visitors from JSONL
    ↓ Extract: visitor_id, history, last_score
    ↓ HTTP POST → OpenAI GPT-4o
    ↓ System prompt: "Analyze patterns..."
    ↓ User prompt: query + JSON data
    ↓ Returns: {found_visitors, patterns, insights, recommendation}
    ↓ WebSocket response → Browser
Dashboard renders results
                    

API Reference

REST Endpoints

POST /api/track

Отправка snapshot данных о поведении посетителя. Возвращает lead_score и опционально trigger.

{
  "trigger_reason": "interval",
  "session": {
    "visitor_id": "v_xxx",
    "device_type": "desktop",
    ...
  },
  "behavior": {
    "time_on_site": 120,
    "total_pages_viewed": 5,
    ...
  }
}
                        

GET /api/dashboard/visitors

Список всех посетителей с фильтрами. Query params: min_score, max_score, device_type, chat_started, awareness_stage, limit.

GET /api/dashboard/visitor/{visitor_id}

Полная история событий конкретного посетителя (все JSONL записи).

GET /api/dashboard/visitor/{visitor_id}/insights

AI-generated insights: awareness_stage, buying_signals, interests, summary.

{
  "lead_score": 78,
  "awareness_stage": "product_aware",
  "awareness_stage_label": "Знает о продукте",
  "buying_signals": ["idle_495_sec_decision_moment"],
  "interests": {"projects": 120, "pricing": 45}
}
                        

GET /api/dashboard/stats

Агрегированная статистика: total_visitors, by_device, by_stage, by_temperature, chat_started.

POST /api/chat

Отправка сообщения в чат. AI генерирует ответ через OpenAI.

WebSocket Endpoints

WS /ws/mcp

MCP AI-анализ через WebSocket. Принимает query, возвращает structured results.

// Client → Server
{"query": "Найди всех с высоким скором"}

// Server → Client
{
  "found_visitors": ["v_xxx", ...],
  "visitor_details": [{...}],
  "common_patterns": [...],
  "insights": [...],
  "recommendation": "..."
}
                        

Data Storage

1. JSONL Event Log

Все события записываются в append-only JSONL файлы:

/opt/smart-collector/backend/logs/visitors/
    v_xxx.jsonl    # Один файл на visitor_id
                    

Формат записи:

{
  "event": "state_update",
  "received_at": "2026-01-07T12:00:00",
  "delta": { /* snapshot data */ }
}
{
  "event": "ai_score_update",
  "received_at": "2026-01-07T12:00:05",
  "data": {"score": 75}
}
{
  "event": "ai_trigger",
  "received_at": "2026-01-07T12:00:30",
  "data": {"message": "Помочь с выбором?", "score": 82}
}
                    

2. SQLite Index

Для быстрых фильтров используется SQLite БД:

/opt/smart-collector/backend/logs/visitors.db

CREATE TABLE visitors (
    visitor_id TEXT PRIMARY KEY,
    last_score INTEGER,
    device_type TEXT,
    chat_started INTEGER,
    awareness_stage TEXT,
    last_seen TEXT,
    total_page_views INTEGER,
    total_time_on_site INTEGER
);

-- Indexes для O(1) поиска
CREATE INDEX idx_score ON visitors(last_score);
CREATE INDEX idx_device ON visitors(device_type);
CREATE INDEX idx_chat ON visitors(chat_started);
CREATE INDEX idx_stage ON visitors(awareness_stage);
                    

AI Services Integration

OpenAI GPT-4o Configuration

class OpenAIService:
    model = "gpt-4o"

    # Scoring
    temperature = 0.3
    max_tokens = 500
    response_format = {"type": "json_object"}

    # Trigger generation
    temperature = 0.7
    max_tokens = 100

    # MCP analysis
    temperature = 0.3
    max_tokens = 2000
                    

Prompt Engineering

Промпты хранятся в отдельных файлах для легкой модификации:

/opt/smart-collector/backend/prompts/
    scoring_prompt.md       # Lead scoring 0-100
    trigger_prompt.md       # Trigger generation
    chat_prompt.md          # Chat responses
                    

💡 Best Practice: Используйте structured outputs (JSON mode) для детерминированности ответов. Всегда валидируйте через Pydantic.

Deployment

System Requirements

Python 3.12+
Nginx 1.24+
2GB RAM minimum (4GB recommended)
1 CPU core minimum (2+ recommended)
10GB disk space

Installation

# 1. Clone repository
git clone https://github.com/your-org/smart-collector
cd smart-collector

# 2. Create virtual environment
python3.12 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env
# Edit .env: OPENAI_API_KEY, PUSHER_* credentials

# 5. Setup systemd service
sudo cp smart-collector.service /etc/systemd/system/
sudo systemctl enable smart-collector
sudo systemctl start smart-collector

# 6. Configure nginx
sudo cp nginx/stats.conf /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/stats.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# 7. Setup SSL (optional)
sudo certbot --nginx -d stats.yourdomain.com
                    

Service Management

# Status check
sudo systemctl status smart-collector

# View logs
sudo journalctl -u smart-collector -f

# Restart
sudo systemctl restart smart-collector

# Check API health
curl http://localhost:8800/api/health
                    

Configuration

Environment Variables

# OpenAI
OPENAI_API_KEY="sk-..."

# Pusher (WebSocket)
PUSHER_APP_ID="..."
PUSHER_KEY="..."
PUSHER_SECRET="..."
PUSHER_CLUSTER="eu"

# Backend
BACKEND_PORT=8800
LOG_LEVEL="INFO"

# Database
DB_PATH="/opt/smart-collector/backend/logs/visitors.db"
LOG_RETENTION_DAYS=30
                    

Tracker Configuration

Настройка клиентского tracker.js:

const tracker = new SmartCollector({
    backendUrl: 'https://stats.mbk-chat.ru',
    visitorId: 'v_xxx',              // Auto-generated or from cookie
    sendInterval: 10000,                  // 10 seconds
    idleThreshold: 30000,                 // 30 seconds
    enableFormTracking: true,
    enableItemTracking: true,
    debug: false
});
                    

Extending the System

Adding Custom Filters

Добавление нового фильтра в Dashboard:

// 1. Update db.py - add column
ALTER TABLE visitors ADD COLUMN custom_field TEXT;

// 2. Update main.py - add query param
@app.get("/api/dashboard/visitors")
async def get_visitors(custom_field: str = None):
    filters["custom_field"] = custom_field

// 3. Update dashboard.html - add filter UI
<select id="filterCustom" onchange="applyFilters()">
    <option value="">All</option>
    <option value="value1">Value 1</option>
</select>
                    

Custom AI Analysis

Создание собственного AI-анализатора:

class CustomAnalyzer:
    def __init__(self):
        self.client = AsyncOpenAI()

    async def analyze(self, visitor_data: dict) -> dict:
        prompt = self._build_prompt(visitor_data)

        response = await self.client.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": "..."},
                {"role": "user", "content": prompt}
            ],
            response_format={"type": "json_object"}
        )

        return json.loads(response.choices[0].message.content)
                    

Playwright Site Analyzer

Автоматический анализ структуры сайта:

from playwright.async_api import async_playwright

class SiteAnalyzer:
    async def analyze(self, url: str):
        async with async_playwright() as p:
            browser = await p.chromium.launch()
            page = await browser.new_page()
            await page.goto(url)

            # Find products
            products = await page.query_selector_all(
                '[data-product-id], .product-card'
            )

            # Find CTA buttons
            cta_buttons = await page.query_selector_all(
                'button:has-text("Купить"), a.btn'
            )

            return {
                "products": len(products),
                "cta_buttons": len(cta_buttons)
            }
                    

Performance Optimization

Caching Strategy

Page Cache: LRU cache на 100 URL для быстрого анализа контента
SQLite WAL mode: Concurrent reads без блокировок
JSONL append-only: O(1) write, sequential read
WebSocket keepalive: Переиспользование соединений

Scaling

# Horizontal scaling with load balancer
nginx upstream backend {
    server 127.0.0.1:8800;
    server 127.0.0.1:8801;
    server 127.0.0.1:8802;
}

# Vertical scaling
uvicorn backend.main:app --workers 4 --host 0.0.0.0 --port 8800
                    

⚠️ Limitation: JSONL и SQLite не подходят для > 100K посетителей/день. Для масштабирования переключитесь на PostgreSQL + Redis.

Security

GDPR Compliance

Анонимизация: visitor_id генерируется клиентом (UUID v4)
PII Protection: НЕ сохраняем значения полей форм, только имена
Phone Numbers: Только флаг has_phone, не само значение
Data Retention: Автоочистка после 30 дней
Right to be Forgotten: DELETE /api/visitor/{id}

API Security

# Rate limiting (nginx)
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

# CORS configuration
allow_origins = ["https://yourdomain.com"]  # Production

# API Key authentication (optional)
@app.middleware("http")
async def verify_api_key(request: Request, call_next):
    api_key = request.headers.get("X-API-Key")
    if api_key != os.getenv("API_KEY"):
        raise HTTPException(401)
    return await call_next(request)
                    

Monitoring & Debugging

Logging

# Application logs
journalctl -u smart-collector -f

# Nginx access logs
tail -f /var/log/nginx/access.log

# Nginx error logs
tail -f /var/log/nginx/error.log

# SQLite query performance
sqlite3 visitors.db ".timer on" "SELECT * FROM visitors WHERE last_score > 70"
                    

Metrics to Track

API response time (p50, p95, p99)
OpenAI API latency
Trigger conversion rate (trigger sent → chat started)
MCP query response time
SQLite query performance
JSONL file size growth

💡 Tip: Используйте Prometheus + Grafana для визуализации метрик или интегрируйте с Sentry для error tracking.

Testing

Unit Tests

# Run tests
pytest tests/ -v --cov=backend

# Test specific module
pytest tests/test_services.py::test_calculate_score

# Example test
def test_lead_scoring():
    service = AIService()
    snapshot = {"behavior": {"time_on_site": 120}}
    score = await service.calculate_score(snapshot)
    assert 0 <= score <= 100
                    

Integration Tests

# Test WebSocket
python3 /tmp/test_mcp.py

# Test API endpoints
curl -X POST http://localhost:8800/api/track -H "Content-Type: application/json" -d @test_snapshot.json

# Load testing
ab -n 1000 -c 10 http://localhost:8800/api/dashboard/visitors
                    

Contributing

Мы приветствуем контрибуции! Следуйте этим рекомендациям:

Fork репозиторий
Создайте feature branch: git checkout -b feature/amazing-feature
Commit изменения: git commit -m 'Add amazing feature'
Push в branch: git push origin feature/amazing-feature
Откройте Pull Request

Code Style

Python: PEP 8, Black formatter, type hints
JavaScript: ESLint, Prettier
Commit messages: Conventional Commits format
Документация: Docstrings для всех публичных методов

🤖 Smart-Collector 📊

Что такое Smart-Collector?

Ключевые возможности

🎯 AI-триггеры

📈 Lead Scoring

🔍 Воронка Ханта

💬 Умный чат

📊 Dashboard

🤖 MCP AI-анализ

Как это работает

Работа с Dashboard

Главная панель

Фильтры посетителей

Карточка посетителя

🤖 MCP AI-анализ

Примеры запросов:

Что вы получите:

Расшифровка терминов

Лучшие практики

Как увеличить конверсию:

Часто задаваемые вопросы

Как часто обновляются данные?

Можно ли отключить триггеры для конкретных страниц?

Как долго хранятся данные о посетителях?

Работает ли система с мобильными устройствами?

Архитектура системы

Технологический стек

Компоненты системы

Data Flow

1. Tracking Pipeline

2. MCP Analysis Pipeline

API Reference

REST Endpoints

WebSocket Endpoints

Data Storage

1. JSONL Event Log

2. SQLite Index

AI Services Integration

OpenAI GPT-4o Configuration

Prompt Engineering

Deployment

System Requirements

Installation

Service Management

Configuration

Environment Variables

Tracker Configuration

Extending the System

Adding Custom Filters

Custom AI Analysis

Playwright Site Analyzer

Performance Optimization

Caching Strategy

Scaling

Security

GDPR Compliance

API Security

Monitoring & Debugging

Logging

Metrics to Track

Testing

Unit Tests

Integration Tests

Contributing

Code Style