# Виджеты и плагины

> Добавляй виджеты, ставь плагины из магазина и управляй автономными плагинами.

Source: https://compico.github.io/ru/overlaycomposer/docs/plugins/
Translation (English): https://compico.github.io/overlaycomposer/docs/plugins/


Есть три способа добавить виджет в макет. Все начинаются с **+ Add Source**.

## 1. Веб-страница (iframe)

Введи адрес любого виджета (тот же, что ты дал бы Browser Source в OBS). Если сайт запрещает встраивание (алерты некоторых сервисов донатов), отметь **Load via server proxy**: программа откроет страницу через себя и уберёт заголовки, запрещающие встраивание. Через прокси работают HTTP, WebSocket и long-poll.

## 2. Локальный HTML-файл

**Add Source → HTML file**: выбери `.html` (CSS, JS и картинки рядом подхватятся) или целую папку. Программа создаст плагин без разрешений в `plugins/local-<имя>/` и поставит его на сцену. Правки в этих файлах подхватываются при перезагрузке страницы виджета. До 64 файлов и 6 МБ; если HTML-файлов несколько, главный назови `index.html`.

## 3. Плагины

Плагин — готовый виджет с настройками и, при необходимости, доступом к чату Twitch, хранилищу или серверной части.

**Add Source → Plugin store…** показывает репозитории плагинов. По умолчанию — [compico/oc-plugins](https://github.com/compico/oc-plugins); можно добавить любой репозиторий в виде `owner/repo`, `owner/repo@ветка-или-тег` или ссылки github.com. Каталог показывает версию каждого плагина, запрашиваемые разрешения и коммит, из которого он собран, а установка, обновление и удаление — кнопкой.

Обновление предлагается, когда версия в репозитории выше (или файлы изменились). Новые разрешения подтверждаются отдельно. Чтобы зафиксировать код, используй тег или коммит: `owner/repo@v1.2.0`. Для приватных репозиториев добавь fine-grained токен GitHub (`Contents: Read-only`) в окне магазина; он хранится зашифрованным и отправляется только на `api.github.com`.

Установленные виджеты появляются в **Add Source → Widgets**. После добавления выбери слой и меняй настройки в панели справа (сохраняются только изменённые значения; ↺ возвращает умолчание).

### Разрешения

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

| Разрешение | Что позволяет |
|---|---|
| `chat.read` | читать чат канала Twitch |
| `chat.send` | писать в чат от имени бота или стримера |
| `storage` | хранить JSON-данные плагина на этом компьютере |
| `net.local` | GET-запросы к программам на этом компьютере (например, tosu) |

Виджет — чужой код. Он работает в изолированном iframe без доступа к API программы, но всё, что ты ему разрешил, он делает от твоего имени: ставь плагины только от авторов, которым доверяешь.

## Автономные плагины (WebAssembly)

Кроме виджетов есть **автономные** плагины: один файл `.wasm`, который работает внутри программы и без собственного окна. Он отвечает на HTTP-запросы, получает события (например, награду за баллы канала), хранит данные, пишет в чат от имени бота, публикует события для других программ и может нести свои виджеты и страницу настроек.

Установка: скачай `<id>.wasm` из релиза плагина (у [compico/oc-plugins](https://github.com/compico/oc-plugins/releases) теги `<id>-v<версия>`) и положи в папку плагинов, либо поставь из магазина. Затем открой **🧩 Plugins** в шапке: **Rescan** подхватывает новые файлы, а в карточке плагина можно выдать разрешения, поменять настройки и перезапустить его.

![Страница настроек плагина заявок на музыку](/overlaycomposer/img/plugin-settings.png)
*Страница настроек плагина `music` (заявки на треки за баллы канала): награда, плеер, очередь и бан-лист.*

| Разрешение | Что позволяет |
|---|---|
| `storage` | хранить данные |
| `net.http` | исходящие HTTP-запросы (никогда в loopback и частные сети) |
| `twitch.redemption` | получать погашения наград, выполнять и отменять их |
| `timer` | таймеры хоста |
| `events.publish` | публиковать события для подписчиков |
| `chat.send` | писать в чат канала стримера от имени бота |

Выдача или смена разрешений перезапускает плагин. Плагин, упавший 5 раз за минуту, останавливается до ручного перезапуска. Всё, что плагин пишет в лог, попадает в лог программы с пометкой `plugin=<id>`.

## Напиши свой

См. [Разработка плагинов](../plugin-development/): HTML-виджеты и автономные плагины на Go.

