Протокол

Сообщения в обе стороны это JSON-объекты с полем type. Неизвестные поля и типы игнорируются, поэтому протокол расширяется без смены версии. Каждое событие от хоста содержит now: монотонное время с запуска плагина в миллисекундах.

context это непрозрачный идентификатор экземпляра действия на конкретной кнопке. Он стабилен, пока действие стоит на этой кнопке этого профиля.

События хоста

Тип	Поля	Когда
`init`	`plugin { id, version }`, `app { version, os, language }`, `device`, `globals`	Первое событие после запуска
`device`	`device`	Устройство подключили, отключили или сменили
`language`	`language`	Пользователь сменил язык интерфейса
`appear`	`context`, `action`, `controller`, `position { column, row }`, `settings`, `state`	Действие появилось на видимой странице
`disappear`	`context`, `action`	Действие ушло со страницы или его удалили
`keyDown`, `keyUp`	`context`, `action`, `settings`, `state`	Нажатие и отпускание кнопки
`tap`	то же	Отпускание без долгого нажатия и удержания, см. жесты
`longPress`	то же	Долгое нажатие
`holdStart`, `holdRepeat`, `holdEnd`	то же, `count` или `duration`	Удержание
`settings`	`context`, `action`, `settings`	Настройки экземпляра изменил пользователь
`globals`	`settings`	Общие настройки плагина изменились вне плагина
`inspectorOpen`, `inspectorClose`	`context`, `action`	Открыта или закрыта страница настроек кнопки
`inspectorMessage`	`context`, `action`, `payload`	Сообщение со страницы настроек кнопки
`settingsPageOpen`, `settingsPageClose`	нет	Открыто или закрыто окно настроек плагина
`settingsPageMessage`	`payload`	Сообщение из окна настроек плагина
`timer`	`id`	Сработал таймер `setTimer`
`httpResponse`	`id`, `status`, `headers`, `body` или `error`	Ответ на `http`
`wsOpen`, `wsMessage`, `wsClose`	`id`, `data` или `reason`	События сокета `wsOpen`
`appStatus`	`id`, `installed`, `processes [{ pid, args }]`	Ответ на `appStatus`
`done`	`id`, `error`	Результат `appLaunch`, `appQuit`, `clipboard`
`denied`	`id`, `message`	Операция запрещена: нет разрешения или согласия

device:

{
  "id": "OSD153R00001",
  "name": "AJAZZ AKP153R",
  "connected": true,
  "keys": { "columns": 5, "rows": 3, "width": 103, "height": 103 },
  "side": { "slots": 3, "width": 85, "height": 103 }
}

Команды плагина

Тип	Поля	Действие
`setTitle`	`context`, `title`, `style`	Подпись. `null` возвращает подпись из манифеста. `style` как у `title` в манифесте
`setImage`	`context`, `image`	Картинка: путь внутри пакета или `data:image/(png\|jpeg\|webp\|svg+xml);base64,…`. `null` возвращает картинку из манифеста
`setState`	`context`, `state`	Номер состояния
`flash`	`context`, `kind`	Короткая отметка `ok` или `alert` поверх кнопки
`setSettings`	`context`, `settings`	Сохранить настройки экземпляра
`setGlobals`	`settings`	Сохранить общие настройки плагина
`toInspector`	`context`, `payload`	Сообщение странице настроек кнопки, если она открыта
`toSettingsPage`	`payload`	Сообщение окну настроек плагина, если оно открыто
`log`	`level`, `message`	Запись в журнал плагина: `debug`, `info`, `warn`, `error`
`openUrl`	`url`	Открыть ссылку `https://` в браузере. Работает в течение 3 секунд после действия пользователя с этим плагином
`setTimer`	`id`, `ms`, `repeat`	Таймер для WASM. Повторный `id` заменяет таймер
`clearTimer`	`id`	Отменить таймер
`http`	`id`, `url`, `method`, `headers`, `body`, `timeout`	HTTP-запрос, см. разрешения
`wsOpen`	`id`, `url`	Открыть WebSocket
`wsSend`	`id`, `data`	Отправить текст
`wsClose`	`id`	Закрыть сокет
`appStatus`	`id`, `app`	Установлено ли приложение и запущено ли
`appLaunch`	`id`, `app`, `args`	Запустить приложение. `args` это числа для шаблонов `{0}`..`{9}`
`appQuit`	`id`, `app`	Вежливо закрыть приложение
`clipboard`	`id`, `text`	Записать текст в буфер обмена

Команда с чужим или исчезнувшим context отбрасывается без ошибки: это обычная гонка между disappear и обновлением кнопки.

Жесты

Хост считает жесты сам. keyDown и keyUp приходят всегда, tap приходит при отпускании любой кнопки. longPress и удержание работают для действий, которые объявили gestures.

Параметр	Что делает
`long_press`	Через столько миллисекунд удержания приходит `longPress`, кнопка ещё нажата
`hold`	Через столько миллисекунд приходит `holdStart`, при отпускании `holdEnd` с `duration`
`repeat`	Пока идёт удержание, каждые столько миллисекунд приходит `holdRepeat` с `count` от 1. Требует `hold`, не меньше 50

tap приходит при отпускании, если до этого не было ни longPress, ни holdStart. Так кнопка с удержанием никогда не получает лишний tap после перемотки. Если исчезает действие или устройство, удержание завершается holdEnd без tap.

Версии

sdk в манифесте меняется только при несовместимых изменениях протокола.
format_version в индексе меняется при несовместимых изменениях формата пакета.
opensd_abi() меняется при несовместимых изменениях ABI.

Новые события, команды и поля добавляются без смены этих номеров.