Документация SquadClans

Как пользоваться сервисом: от входа через Steam до управления кланом, заявками, группами прав и API-ключами.

Разделы

Регистрация Профиль игрока Поиск кланов Заявки Создание клана Редактирование клана Роли и состав Роль-группы Журналы и заметки Лидер клана API Администрирование

Регистрация и вход

Для обычного пользователя вход выполняется через Steam. После успешного входа сервис сохраняет SteamID, никнейм и аватар из Steam. SteamID используется как основной идентификатор игрока.

Нажмите Войти через Steam в шапке сайта.
Подтвердите вход на стороне Steam.
После возврата на сайт в шапке появится ваш никнейм и кнопка выхода.
Нажатие на никнейм открывает ваш профиль игрока.

Профиль игрока

В профиле отображаются никнейм, SteamID, общее время игры, описание игрока, опыт игры, киты, статистика и личное дело.

Редактировать профиль может только сам игрок.
В профиле можно заполнить «О себе», «Опыт игры и предпочитаемые киты», месяц и год рождения, часовой пояс.
В редакторе профиля можно выбрать любимые игровые роли нажатием на иконки. Выбранные роли отображаются в профиле игрока и в составе клана.
В редакторе профиля можно нажать Привязать Discord и пройти авторизацию Discord. После возврата сервис сам сохранит Discord ID и имя, а в профиле игрока появится кнопка для связи через Discord.
Возраст видят только владельцы, офицеры и рекрутеры кланов.
События в личном деле отображаются во временной зоне пользователя, который смотрит профиль.
SteamID в профиле является ссылкой на Steam-профиль игрока.

Поиск и подбор клана

На главной странице показан список зарегистрированных кланов Squad. Карточка клана открывает профиль клана.

Глобальный поиск в шапке ищет кланы и игроков по названию, тегу, нику и SteamID.
Фильтр на главной странице позволяет искать по статусу набора, возрастным ограничениям, требованиям по часам, цели клана и избранному.
Кланы можно сортировать по названию и количеству участников.
Звезда на карточке или в профиле клана добавляет клан в избранное.

Подача заявки в клан

Подать заявку может только пользователь, вошедший через Steam и не состоящий в другом клане.

Откройте профиль клана.
Если клан ведет набор и вы не состоите в клане, будет доступна подача заявки.
Напишите короткое сообщение о себе и отправьте заявку.
Пока заявка не обработана, ее можно отменить.

Заявки видят участники клана с правом управления составом. По заявке можно принять игрока в рекруты, принять сразу в основной состав или отклонить.

Создание своего клана

Создать клан может игрок, который вошел через Steam, не состоит в другом клане и набрал минимальное количество игровых часов, заданное в настройках сервиса.

Если игрок не состоит в клане, в шапке отображается кнопка Создать клан. Если часов не хватает, кнопка видна, но неактивна.

При создании клана заполняются:

основной тег клана;
название клана;
резервные варианты тегов;
краткое и полное описание;
возрастные ограничения;
минимальный опыт в часах;
цель клана;
статус набора.

После создания клана создатель становится лидером клана, а событие записывается в его личное дело.

Редактирование профиля клана

Кнопка Редактировать в профиле клана видна пользователям, у которых есть хотя бы одно право на редактирование.

В редакторе можно менять:

описание, краткое описание, цель, набор, возрастные ограничения и требования по часам;
основной тег, название и резервные теги, если пользователь является лидером;
тег рекрутов;
настройку пробела после тега;
логотип клана;
ссылки на Discord, YouTube, Twitch и Telegram;
Discord webhook для уведомлений в канал сервера и список событий, которые надо отправлять.

Webhook URL является секретом: после сохранения он не показывается обратно в интерфейсе, а отображается только статус подключения. Если Discord временно недоступен или webhook удален, основное действие на сайте все равно завершается, а ошибка отправки записывается в серверный лог.

Логотип загружается в формате PNG или JPG. Сервер проверяет формат файла, ограничивает размер загрузки и разрешение изображения, затем конвертирует логотип в PNG 512x512 и сохраняет файл с именем по id клана.

Роли и состав клана

В клане есть один лидер. Остальные роли задаются через роль-группы: это обычные группы прав, у которых выбран тип роли. Добавление игрока в такую группу одновременно назначает ему роль и выдает права этой группы.

Лидер управляет всем кланом, может передать лидерство и распустить клан.
Старший офицер - роль-группа для расширенного управления. По умолчанию получает все делегируемые права.
Офицер - роль-группа для работы с составом, заявками и внутренними заметками.
Рекрутер - роль-группа для работы с набором игроков.
Участник - роль-группа без специальных прав по умолчанию.
Рекрут не является роль-группой. Это отдельный статус игрока до перевода в основной состав.

В профиле клана основной состав и рекруты показываются отдельно. Основной состав сортируется так: лидер, старшие офицеры, офицеры, рекрутеры, участники, затем по алфавиту. Участники отображаются с клановым тегом перед никнеймом.

Роль-группы и права клана

Группы прав позволяют лидеру делегировать управление кланом другим участникам. В редакторе клана у группы можно выбрать тип: произвольная группа, старший офицер, офицер, рекрутер или участник.

Стандартные роль-группы создаются автоматически при создании клана. Их можно переименовывать, менять права и состав участников.

Группе можно выдать права:

изменение описания, короткого описания, возрастных ограничений, статуса набора и требований;
изменение логотипа;
редактирование групп;
добавление и удаление игроков;
редактирование роль-групп и назначение игроков в эти группы;
чтение внутренних заметок на игроках;
создание и редактирование внутренних заметок на игроках;
экспорт SteamID участников групп в буфер обмена или текстовый файл.

Добавление пользователя в группу выполняется через поиск среди текущих игроков основного состава. Рекрутов в роль-группы не добавляют: сначала игрок переводится в основной состав. Если игрок выходит из клана или его исключают, его групповые права сбрасываются.

Журналы, личное дело и заметки

По каждому клану ведется журнал событий: заявки, принятие, отклонение, исключение, перевод в основной состав, смена лидера и роспуск.

Журнал клана видят только пользователи с правом управления составом.
Журнал можно фильтровать по дате, времени, игроку и офицеру.
В личное дело игрока попадают события вступления, выхода, исключения, перевода, лидерства и роспуска клана.
Время отображается в часовом поясе пользователя, который просматривает страницу.

Внутренние заметки клана по игроку открываются кнопкой Заметки клана в профиле игрока. Эти заметки видят только участники клана с правом чтения заметок. Писать и редактировать заметки могут только те, кому выдано соответствующее право.

Лидер клана: передача и роспуск

В редакторе клана лидер видит блок управления владельцем.

Передать роль лидера можно только игроку из основного состава. Передача требует повторного подтверждения.
После передачи прежний лидер становится обычным членом клана, а его настроенные группы и права сохраняются.
Распустить клан может только лидер клана или администратор проекта. Роспуск требует повторного подтверждения.
При роспуске все игроки теряют членство в клане, а в личное дело записывается выход из-за роспуска клана.

API и токены

Сервис поддерживает работу через API. Токены выдаются администратором проекта в панели Админ.

Для запросов используйте заголовок:

Authorization: Token ВАШ_API_КЛЮЧ

Полезные API-разделы:

/api/clans/ - список кланов;
/api/clans/{id}/ - профиль клана;
/api/clans/{id}/members/ - состав клана;
/api/users/ - поиск пользователей;
/api/player-history/ - личное дело игрока;
/api/applications/ - заявки, доступные пользователю;
/api/clantagguard/check/ - одиночная проверка права игрока носить зарегистрированный клановый тег для SquadJS-плагина;
/api/clantagguard/check-batch/ - пакетная проверка списка игроков для периодической проверки SquadJS-сервера.

Для плагина clantagguard создайте отдельный ключ в панели /project-admin/ в блоке Ключи ClanTagGuard. При создании указывается название сервера и заметка, чтобы было понятно, где используется ключ. Полученный ключ передается в настройке secretToken. Плагин отправляет методом POST только steam_id и player_name, а сервис сам ищет зарегистрированный клановый тег в имени игрока и принимает решение. Если тег зарегистрирован, но SteamID не состоит в составе этого клана, API вернет allowed: false.

{
  "plugin": "clantagguard",
  "enabled": true,
  "apiUrl": "https://squadclans.ru/api/clantagguard/check/",
  "batchApiUrl": "https://squadclans.ru/api/clantagguard/check-batch/",
  "secretToken": "ВАШ_СЕКРЕТНЫЙ_ТОКЕН",
  "enforcementMode": "backend",
  "broadcastWarning": true,
  "periodicCheckEnabled": true,
  "periodicCheckIntervalMs": 600000,
  "skipChecksWhenApiUnavailable": true,
  "apiFailureThreshold": 3,
  "apiFailureCooldownMs": 60000
}

Плагин проверяет игрока при подключении и дополнительно раз в periodicCheckIntervalMs отправляет текущий список игроков одним пакетным запросом. По умолчанию это 10 минут. Если API SquadClans временно недоступен, плагин работает в режиме fail-open: не предупреждает и не кикает игроков, а после нескольких ошибок на время приостанавливает проверки, чтобы не мешать работе SquadJS и других плагинов.

Ответ API содержит поле action: log, warn или kick. По умолчанию плагин использует enforcementMode: "backend" и выполняет действие, которое вернул сервис. На конкретном SquadJS-сервере можно принудительно заменить поведение, указав enforcementMode: "log", "warn" или "kick". Глобальная реакция настраивается в /project-admin/, а при варианте «как указано в профиле клана» используется настройка самого клана.

Проверка учитывает статус игрока в клане: основной и резервные теги разрешены только основному составу. Рекрут может носить тег рекрутов, но если он поставит основной или резервный тег, защита вернет отказ с причиной recruit_using_main_tag.

Когда защита срабатывает, в панели /project-admin/ в блоке Журнал ClanTagGuard появляется запись: дата и время, сервер, клантег, клан, SteamID, имя игрока и действие, которое было отправлено плагину.

Секреты внешних сервисов, ключи Steam, playtime и статистики хранятся только в серверном окружении и не передаются во фронтенд.

Администрирование проекта

Панель администратора проекта доступна по адресу /project-admin/ только пользователям с флагом is_staff.

В панели можно:

смотреть сводку по пользователям, кланам, членствам, заявкам и API-ключам;
искать пользователей по нику и SteamID;
выдавать, перевыпускать и отзывать API-ключи;
настраивать глобальную реакцию ClanTagGuard: только логировать, предупреждать, кикать или брать настройку из профиля клана;
создавать отдельные ключи ClanTagGuard для SquadJS-серверов, указывать название сервера и заметку, отключать или перевыпускать ключи;
смотреть журнал срабатываний ClanTagGuard по серверу, клантегу, SteamID и имени игрока;
открывать кланы;
удалять кланы, если они нарушают правила или заняли чужой тег.

Удаление клана администратором работает как роспуск: активные членства закрываются, игроки получают запись в личное дело, логотип и данные клана удаляются.

Стандартная Django-админка также доступна по адресу /admin/ для технического обслуживания.