Аналитика игроков (HelgaAnalytics)

HelgaAnalytics — свой плагин, исходники лежат в plugins-src/HelgaAnalytics. Он записывает, кто заходит на сервер, авторизуется, ставит участок, покупает в магазине, голосует и возвращается на следующий день, и показывает это отчётами в консоли. Ничего не отправляет наружу и ничего не делает с игроками.

На хостинг пока не выложен. Проверенные jar лежат в plugins-src/HelgaAnalytics/dist, подробная техническая документация — README.md и docs/ в том же репозитории.

Установка

1. Сделать бэкап в панели (вкладка Backups) — см. «Бэкапы».
2. Остановить сервер.
3. Загрузить в plugins/ три файла из dist/, заменяя старые:
   • HelgaAnalytics-1.0.0.jar;
   • HelgaShop-1.0.0.jar — с событием покупок для аналитики и новым меню с подменю. Новый menu.yml плагин сам не подставляет — его нужно загрузить вручную, см. «Главное меню /help»;
   • HelgaVote-1.0.0.jar — с событиями голосов.
4. Запустить сервер (не /reload).
5. В консоли analytics status. Должно быть «Запись: работает»; Авторизация, Участки, Покупки, Голоса — «работает». Обучение, Рейды, Подтверждение доставки — «источник не подключён», Профессии — «нет надёжного источника». Это нормально: таких данных на сервере пока нет.
6. Убрать персонал из статистики: lp group <группа> permission set helgaanalytics.exclude true (действует со следующего входа). Тестовые ники — в plugins/HelgaAnalytics/config.yml, раздел exclusions, затем analytics reload.

Со старыми HelgaShop/HelgaVote аналитика работает, но покупки и голоса будут «нет данных», а analytics status покажет «не подключилась».

Команды

Команда	Что делает
analytics status	всё ли пишется: очередь, потери, ошибки, интеграции
analytics report 7d	сводка за неделю (today, yesterday, 30d, 2026-10-01..2026-10-14)
analytics retention 30d	возвращаемость D1/D7/D30 по дням первого входа; … new — только зарегистрированные при работающем модуле
analytics funnel 30d	что делают новички в первую неделю: участок, покупка, голос
analytics export 30d csv	файл с цифрами в plugins/HelgaAnalytics/exports/ (или json)
analytics player <ник>	диагностика одного аккаунта — закрытые сведения
analytics reload	перечитать config.yml и messages.yml

Алиас — /ha. Период — не длиннее 92 дней. Тяжёлые отчёты строятся по одному и не чаще раза в 5 секунд на человека.

Право	Кому по умолчанию	Что даёт
helgaanalytics.status	OP	status
helgaanalytics.report	OP	report, retention, funnel
helgaanalytics.export	OP	export
helgaanalytics.player	OP	player — отдельное право, не входит в admin
helgaanalytics.admin	OP	reload; включает status/report/export
helgaanalytics.exclude	никому	аккаунт не попадает в отчёты

Обычный игрок ничего из этого не видит. Выгрузки содержат только цифры — без ников, UUID и IP, их можно пересылать команде.

Как читать отчёты

Строка retention:

2026-10-20 n=40 (рег. 31) D1 45% (18/40) D7 20% (8/40) D30 N/A (рано, n=40)

• 2026-10-20 — день, когда эти аккаунты впервые авторизовались по журналу модуля; n=40 — сколько их, рег. 31 — из них зарегистрировались именно тогда (точно новички).
• D1 — зашли на следующий календарный день, D7 — ровно на седьмой, D30 — на тридцатый. Сессия через полночь засчитывает оба дня.
• «за 7 дн.» — зашёл хотя бы раз за первую неделю. Это мягче, чем D7.
• N/A (рано) — день ещё не наступил или не закончился. Это не ноль.
• * у даты — первые две недели журнала: туда попадают и старые игроки, которых модуль увидел впервые. Для оценки новичков — retention 30d new или когорты без звёздочки.

Пометки в сводке и воронке:

Пометка	Значит
0	источник работал, событий не было
нет данных	источника нет или он не работал — это не 0%
(неполные данные…)	источник работал не весь период
«Период начинается раньше журнала»	до установки модуля ничего не известно
«Пропуски записи»	сервер или диск не успевал, часть событий потеряна — число указано
«Аварийных остановок»	сервер падал, длительность тех сессий известна приблизительно

Время в отчётах — новосибирское, в базе хранится UTC. Длительность — это длительность авторизованной сессии, AFK не определяется.

Что записывается

Событие	Откуда
вход в мир, выход	Paper
успешный вход, неверный пароль, регистрация	AuthMe (только подтверждённый вход, не сама команда /login)
создан участок	GriefPrevention (только если участок действительно сохранился; деления и админские — отдельно)
покупка, отказ, возврат, подарок	HelgaShop, после завершения покупки
голос принят, награда отправлена	HelgaVote

Не собирается: пароли и аргументы команд, чат, IP, токены, координаты участков. Аккаунты не склеиваются по IP — «уникальных людей» модуль не знает, только аккаунты.

Пока без данных:

• выбор профессии — у JobSystem нет событий и API;
• обучение и рейды — модулей нет, API для них готов;
• доставка награды за голос — HelgaVote знает только, выполнились ли команды награды (всё, что не выполнилось, уходит админу на /voteadmin review). В аналитике видно «команды выполнены», «команда не найдена/упала» по последней попытке и сколько наград выдавали повторно; подтверждения, что игрок получил награду, нет.

Если что-то не так

• analytics status пишет «база недоступна» или «ошибка, повторяю» — проверить место на диске хостинга. Игре это не мешает: события копятся в памяти (до 10 000), дальше теряются с пометкой в отчётах.
• Интеграция «не подключилась» — стоит старый HelgaShop/HelgaVote.
• После падения сервера в analytics status будет «закрыто после аварии». Это нормально: незакрытые сессии помечаются, концом считается последняя отметка «сервер жив» (раз в 30 секунд).
• Убрать модуль: удалить jar и перезапустить. Магазин и голосование работают без него.

Файлы

Файл	Что
config.yml	часовой пояс, исключения, сроки хранения, размер очереди
messages.yml	все тексты
analytics.db	база SQLite — в бэкап; копировать вручную только при остановленном сервере
exports/	выгрузки analytics export

Сырые события хранятся 90 дней, сессии — 400. Первые факты аккаунта (первый вход, регистрация, первый участок, первая покупка) не удаляются, поэтому когорты не портятся очисткой.

debug.commands в config.yml — только для тестового стенда, на сервере держать false.