Перейти к основному содержимому

Разработка плагинов

Плагин — это дополнение, которое устанавливается прямо в Loop и меняет его поведение: добавляет кнопки и панели в интерфейс, собственные slash-команды, ботов, реагирует на сообщения и события. В отличие от вебхуков и REST API, плагину не нужен отдельный сервер: он работает внутри Loop.

Этот раздел рассчитан на тех, кто никогда не писал плагины. Если вы умеете запускать команды в терминале и хоть немного читали код на Go или JavaScript, этого хватит. Все сложные слова объясняются по ходу дела.

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

Loop совместим с плагинами Mattermost 9.11.7: плагины для Loop пишутся так же, как для Mattermost этой версии, с теми же инструментами. Возможности плагинов, которые появились в Mattermost позже, в Loop недоступны. Подробнее — в разделе Совместимость с Mattermost.

Когда нужен плагин​

ЗадачаЧто выбрать
Отправлять уведомления из CI, мониторинга, CRMВходящий вебхук — плагин не нужен
Команда /что-то, которая вызывает ваш внешний сервисСобственная slash-команда — плагин не нужен
Бот, который живёт на вашем сервере и работает через APIБот-аккаунт и REST API
Своя кнопка, панель, пункт меню или окно в интерфейсе LoopПлагин
Проверить или изменить сообщение до публикации (например, запретить слово)Плагин
Реагировать на события внутри Loop: вход пользователя, создание канала, реакциюПлагин
Интеграция, которую администратор ставит одним файлом, без отдельного сервераПлагин

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

Из чего состоит плагин​

Плагин — это один архив .tar.gz. Внутри три части:

my-plugin.tar.gz
├── plugin.json          ← манифест: паспорт плагина (название, версия, настройки)
├── server/              ← серверная часть: программа на Go
└── webapp/              ← клиентская часть: код на React/TypeScript
ЧастьГде работаетЧто умеетОбязательна?
Манифест plugin.json—Сообщает Loop, как называется плагин, какой он версии, какие у него настройки и где лежат остальные частиДа
Серверная часть (Go)На сервере Loop, отдельным процессомSlash-команды, боты, обработка сообщений и событий, своё HTTP API, хранение данныхНет
Клиентская часть (React)В браузере и десктоп-приложении пользователяКнопки, панели, пункты меню, свои типы сообщений, окнаНет

Можно сделать плагин только с серверной частью (например, бот-модератор) или только с клиентской (например, кнопка, которая открывает внешний сайт). Но обычно нужны обе: интерфейс спрашивает данные у сервера плагина.

Мобильное приложение

Клиентская часть работает в веб-версии и десктоп-приложении Loop. Мобильное приложение код плагинов не загружает, но результаты серверной части — сообщения, боты, slash-команды — видны везде.

Как плагин работает внутри Loop​

Браузер пользователя                  Сервер Loop
┌──────────────────────┐              ┌──────────────────────────────────┐
│ Loop                 │              │ Loop                             │
│  └ клиентская часть  │ ── HTTP ───► │   │  хуки: «новое сообщение»,    │
│    плагина (React)   │ ◄─ события ─ │   │  «вызвали команду» ...       │
└──────────────────────┘              │   ▼                ▲             │
                                      │ серверная часть ───┘             │
                                      │ плагина (Go)   API: «опубликуй», │
                                      │                «найди канал» ... │
                                      └──────────────────────────────────┘
  • Хуки (hooks) — это события, о которых Loop сообщает плагину. Например, MessageHasBeenPosted — «в канале появилось сообщение». Плагин пишет функцию с таким именем, и Loop вызывает её каждый раз, когда событие происходит.
  • API плагинов — набор функций, которыми плагин управляет Loop: CreatePost публикует сообщение, GetUser находит пользователя, KVSet сохраняет данные и т. д.
  • Реестр (registry) — то же для клиентской части: через него плагин говорит «добавь мою кнопку в шапку канала» или «покажи мою панель справа».

Серверная часть — отдельная программа. Loop запускает её сам при включении плагина и перезапускает, если она упала. Благодаря этому ошибка в плагине не роняет весь Loop.

Словарик​

СловоЧто значит
МанифестФайл plugin.json с описанием плагина
ID плагинаУникальное имя плагина, например ru.loop.plugin.hello. Никогда не меняйте его после выпуска: для Loop это будет другой плагин
ХукФункция плагина, которую вызывает Loop при событии
БандлСобранный архив плагина .tar.gz, который загружается в Loop
WebappКлиентская часть: то, что выполняется в браузере
RHS (Right Hand Sidebar)Правая боковая панель Loop, где открываются треды, поиск и панели плагинов
KV-хранилищеПростая база «ключ → значение», которую Loop даёт каждому плагину
Системная консольРаздел настроек для системного администратора Loop

С чего начать​

  1. Быстрый старт — соберите шаблон и установите свой первый плагин.
  2. Пошаговый пример — сделайте плагин с ботом, slash-командой, настройками и панелью в интерфейсе.
  3. Дальше используйте разделы про серверную и клиентскую части как справочник.

Разделы​