Обзор пользовательских виджетов

Пользовательский виджет — небольшое фронтенд-приложение в ZIP-архиве. Его можно запустить приватно в своём аккаунте или опубликовать после отдельной модерации исполняемого релиза и карточки маркетплейса. Bito раздаёт одобренные файлы и загружает их в админ-панель, где код рисует себя внутри экранов продукта: вкладкой профиля, пунктом меню номера телефона, постоянным фоновым виджетом или собственной страницей настроек.

Если вы писали виджет для amoCRM, форма будет знакома: script.js — это AMD-модуль, который возвращает конструктор CustomWidget с объектом callbacks, и ему передаётся jQuery 4 ($).

Виджет не изолирован. Совсем.

Ваш script.js подключается обычным <script src> и исполняется в собственном origin и сеансе админ-панели. Он может вызывать любой admin-эндпоинт от имени вошедшего пользователя, читать DOM любого экрана и работать с браузерным хранилищем ERP. Нет ни iframe, ни sandbox-атрибута, ни отдельного CSP для виджета, ни системы разрешений, сужающей то, к чему он может прикоснуться.

Контроль — это экран согласия компании на конкретный релиз, а не изоляция. Устанавливая ваш виджет, компания доверяет лично вам, разработчику, всё, что может делать вошедший пользователь, включая данные по продажам, финансам и зарплате. Bito проверяет заявки, но не даёт гарантий за сторонний код.

Это замена прежнего iframe-виджета, где ваша собственная страница встраивалась в iframe во вкладке настроек интеграции. Тот механизм всё ещё существует для встроенных интеграций самого Bito (iframe.url плюс одноразовый токен), но пользовательский виджет работает не так.

Как это устроено

  Разработчик                      Bito                        Компания
      |                              |                              |
      |  1. Собрать widget.zip       |                              |
      |  2. Заполнить карточку,      |                              |
      |     создать релиз и          |                              |
      |     загрузить архив          |                              |
      |----------------------------->|                              |
      |     отчёт валидации          |                              |
      |<-----------------------------|                              |
      |  3. Проверить локально и     |                              |
      |     отправить релиз          |                              |
      |----------------------------->|                              |
      |                              |  4. Модерация релиза         |
      |                              |     одобрение -> файлы       |
      |                              |     распакованы и запускаемы |
      |  5. Отправить карточку       |                              |
      |<-----------------------------|                              |
      |                              |  6. Карточка одобрена -> public|
      |                              |  7. Компания устанавливает   |
      |                              |<-----------------------------|
      |                              |  8. Директор принимает       |
      |                              |     согласие на ЭТОТ релиз   |
      |                              |<-----------------------------|
      |                              |  9. mount -> script.js       |
      |                              |     работает в панели        |

Откуда раздаются файлы

Одобренные файлы распаковываются и раздаются с отдельного регистрируемого домена, а не с поддомена bito.uz. Это даёт изоляцию cookie и меньший радиус поражения кеша — но не изолирует ничего. Кросс-доменный <script src> всё равно исполняется в той странице, которая его загрузила, — в этом и весь смысл модели.

Файлы отдаются с X-Content-Type-Options: nosniff и типом содержимого, назначенным на сервере по списку разрешённых расширений, а не по тому, что прислали вы.

Согласие даётся на релиз

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

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

Из чего состоит виджет

Файл	Обязателен	Назначение
manifest.json	Да	Версия интерфейса, языки, точки монтирования, раскрываемые адреса
script.js	Да	AMD-модуль, возвращающий ваш CustomWidget
i18n/<lang>.json	По одному на каждый заявленный язык	Плоский словарь ключ → строка, выбирается на сервере
style.css	Нет	Подключается к документу хоста как <link>
templates/	Нет	Именованные шаблоны для bito.render()
images/	Нет	Статические файлы

Полные правила и лимиты: формат widget.zip.

Читать дальше

Страница	На какой вопрос отвечает
Формат widget.zip	Что кладётся в архив и из-за чего его отклонят
Жизненный цикл CustomWidget	Какие колбэки вызываются, в каком порядке и что будет при исключении
Справочник bito SDK	Каждый метод window.bito
Точки монтирования	Где именно в продукте может появиться виджет
Совместимость с jQuery	Что заменено в поставляемом jQuery 4
Публикация релиза	Версии, очередь проверки, что меняет одобрение
Страница приложения	Отдельные процессы карточки маркетплейса и релиза
Как стать разработчиком Bito	Как получить аккаунт, которому всё это доступно