Расширения

Введение

Системный каталог Расширения используется для управления расширениями функциональности веб-клиента Бипиум. Расширения позволяют добавлять дополнительный функционал в интерфейс через загрузку JavaScript и CSS файлов. Доступность расширений для компаний определяется через лицензию.

Каталог Расширения доступен администраторам серверной версии Бипиум и используется для управления расширениями в системе.

Назначение каталога

Каталог Расширения используется для:

• Управления расширениями: создание, редактирование и удаление записей расширений

• Настройки функциональности: указание JavaScript и CSS файлов для загрузки в веб-клиент

• Конфигурации интерфейса: настройка названия, иконки и кода расширения для отображения в меню

Доступ к каталогу

Каталог Расширения находится в разделе Система и доступен только администраторам сервера Бипиум.

Как открыть каталог:

1. Войдите в систему с правами администратора

2. Перейдите в раздел Система (в главном меню)

3. Выберите каталог Расширения

Поля каталога

Поля в каталоге отображаются в следующем порядке:

Поле	Тип	Описание
Название	Текст	Название расширения, отображается в меню веб-клиента
Код	Текст	Уникальный код расширения, используется для идентификации расширения в системе
Иконка	Текст	Класс иконки для отображения в меню веб-клиента
JS URL	Текст (многострочное)	URL или путь к JavaScript файлу расширения, который будет загружен в веб-клиент
CSS URL	Текст (многострочное)	URL или путь к CSS файлу расширения, который будет загружен в веб-клиент

Важная информация

Использование расширений

Расширения используются для добавления дополнительного функционала в веб-клиент Бипиум:

• JavaScript файлы: добавляют новую функциональность, обработчики событий, интеграции с внешними системами

• CSS файлы: изменяют внешний вид интерфейса, добавляют стили для новых элементов

Типы расширений

Расширения могут быть разных типов в зависимости от способа их работы:

• Модальные — открываются в отдельном слое поверх открытого раздела в Бипиум (например, каталога с записями). Могут занимать часть экрана или всю рабочую область приложения. При этом основной экран приложения Бипиум остается в DOM-дереве. Пример — панель телефонии Oktell.

• Экранные — экранные модули занимают всю рабочую область приложения, замещая в DOM-дереве открытый раздел приложения. Этот тип расширений поддерживается пока не полностью.

• Фоновые — веб-расширение работает в фоне и управляет DOM-деревом (встраивает элементы) в нужный ему момент.

Доступность расширений для компаний

Доступность расширений для компаний определяется через лицензию:

• Расширения не привязываются напрямую к компаниям через поле в каталоге Компании

• Система проверяет наличие расширения в лицензии компании по коду расширения

• Только расширения, разрешенные лицензией компании, будут доступны в веб-клиенте этой компании

Важно: Для того чтобы расширение было доступно компании, необходимо:

1. Зарегистрировать расширение в системе лицензирования Бипиум (смотрите раздел Регистрация расширений)

2. Создать запись расширения в каталоге Расширения с указанием кода, названия, иконки и URL файлов

3. Убедиться, что расширение разрешено в лицензии компании (проверяется по коду расширения)

Без регистрации расширения в системе лицензирования подключить его будет невозможно.

• Администратор сервера может создавать расширения в каталоге Расширения самостоятельно

• Важно: Сервер лицензирования находится только у разработчиков Бипиум. Все проверки и добавления расширений в лицензии выполняются только через сервер лицензирования разработчиков

• Для того чтобы созданное расширение было доступно компаниям, необходимо зарегистрировать его в системе лицензирования

• После регистрации разработчики Бипиум добавят код расширения в лицензию компании через сервер лицензирования

• Лицензии проверяются на валидность подписи при загрузке. Система автоматически получает обновленные лицензии с сервера лицензирования платформы

Загрузка расширений

Размещение файлов расширений

Файлы расширения необходимо разместить одним из способов:

1. На локальном сервере Бипиум:

   • Разместите файлы в рабочей папке на сервере Бипиум: bpium_path/www/modules/my-extension/

   • Если у вас несколько серверов, разместите файлы на каждом сервере

   • Используйте относительные пути в полях JS URL и CSS URL, например: modules/my-extension/main.js

2. На внешнем веб-сервере:

   • Разместите файлы на любом веб-сервере, доступном по HTTP/HTTPS

   • Используйте абсолютные URL в полях JS URL и CSS URL, например: https://example.com/extensions/my-extension/main.js

Примечание: Файлы расширений должны быть доступны по указанным в полях JS URL и CSS URL адресам. После создания или обновления записи расширения изменения применяются для всех компаний, имеющих доступ к расширению через лицензию.

Механизм загрузки расширений в веб-клиент

Расширения загружаются в веб-клиент динамически при входе пользователя в систему:

1. При авторизации пользователя веб-приложение Бипиум делает запрос к серверу: /auth/company

2. Ответ сервера содержит набор подключенных расширений:

   {
     "domain": "admin",
     "title": "Моя компания",
     "extensions": [ /* массив расширений */ ]
   }

3. Проверка лицензии: система проверяет каждое расширение из каталога Расширения на наличие в лицензии компании по коду расширения

4. Фильтрация: только расширения, разрешенные лицензией, возвращаются в ответе. Сервер не вернет расширения, на которые не получена лицензия для компании

5. Загрузка файлов: веб-клиент загружает JavaScript и CSS файлы расширений

6. Инициализация: после загрузки файлов расширения инициализируются и становятся доступными в интерфейсе

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

Регистрация расширения

Важно: Все расширения проходят через систему лицензирования. Подключение расширения к системе возможно только при наличии лицензии на это расширение в лицензии компании.

Как зарегистрировать расширение?

Чтобы зарегистрировать расширение в системе лицензирования Бипиум:

1. Выберите уникальный код расширения:

   • Код может состоять из латинских букв, цифр и знака дефис

   • Код должен быть уникальным и не использоваться другими расширениями

   • Код должен совпадать с названием модуля в скрипте (переменная moduleName)

2. Напишите письмо на почту [email protected] с указанием:

   • Выбранного уникального кода расширения

   • Вашего регистрационного номера лицензии

3. Дождитесь подтверждения регистрации от технической поддержки Бипиум

КРИТИЧНО: Без регистрации расширения в системе лицензирования подключить его будет невозможно. Даже если вы создадите запись в каталоге Расширения и разместите файлы, расширение не будет доступно компаниям без регистрации в системе лицензирования.

Практические сценарии

Как работает проверка доступа к расширениям?

Система проверяет доступность расширений для компании в следующем порядке:

1. Получение всех расширений: система получает все записи из каталога Расширения

2. Проверка лицензии: для каждого расширения проверяется наличие его кода в параметрах лицензии компании (в поле Модули)

3. Фильтрация: только расширения, разрешенные лицензией, возвращаются в веб-клиент

4. Загрузка: веб-клиент загружает только разрешенные расширения

Пример:

• В каталоге Расширения есть расширение с кодом my-extension

• В лицензии компании в поле Модули указан код my-extension

• Расширение будет доступно для этой компании и загрузится в веб-клиент

Если код расширения не указан в лицензии компании, расширение не будет доступно, даже если оно существует в каталоге.

Как расширения отображаются в интерфейсе?

Расширения могут отображаться в меню веб-клиента:

• Название расширения отображается как пункт меню

• Иконка отображается рядом с названием (используется класс иконки из поля Иконка)

• Расширения отображаются только для компаний, имеющих доступ к ним через лицензию

Примечание: Не все расширения обязательно отображаются в меню. Это зависит от реализации самого расширения. Расширения могут работать в фоновом режиме, добавляя функциональность без видимых элементов интерфейса.

Работа с каталогом

Как создать расширение?

ВАЖНО: Перед созданием расширения в каталоге необходимо зарегистрировать его в системе лицензирования Бипиум (см. раздел "Регистрация расширения"). Без регистрации расширение не будет работать.

Для создания нового расширения в каталоге:

1. Зарегистрируйте расширение в системе лицензирования (см. раздел "Регистрация расширения")

2. Разместите файлы расширения на сервере или внешнем веб-сервере (см. раздел "Размещение файлов расширений")

3. Откройте каталог Расширения в разделе Система

4. Нажмите кнопку создания новой записи

5. В поле Название укажите название расширения (будет отображаться в меню)

6. В поле Код укажите уникальный код расширения:

   • Код должен совпадать с кодом, указанным при регистрации

   • Код должен совпадать с названием модуля в скрипте (переменная moduleName)

   • Используется для идентификации в системе и проверки лицензии

7. В поле Иконка укажите класс иконки для отображения в меню (список доступных значений см. в документации)

8. В поле JS URL укажите URL или путь к JavaScript файлу расширения:

   • Для локально размещенного расширения: modules/my-extension/main.js

   • Для внешнего расширения: https://example.com/extensions/my-extension/main.js

   • Можно указать несколько URL, каждый с новой строки

9. В поле CSS URL укажите URL или путь к CSS файлу расширения:

   • Для локально размещенного расширения: modules/my-extension/main.css

   • Для внешнего расширения: https://example.com/extensions/my-extension/main.css

   • Можно указать несколько URL, каждый с новой строки

10. Сохраните запись

11. Обновите страницу в браузере

Примечание:

• Код расширения должен быть уникальным в системе и совпадать с кодом, указанным при регистрации

• URL файлов могут быть абсолютными (например, https://example.com/extension.js) или относительными (например, modules/my-extension/main.js)

• Для использования расширения в компании необходимо убедиться, что расширение разрешено в лицензии компании

• Можно указать несколько URL в полях JS URL и CSS URL (каждый URL с новой строки) — все файлы будут загружены в указанном порядке

• После сохранения записи проверьте консоль браузера (вкладка Network) — должны быть видны запросы к вашим файлам

Пример создания расширения:

Название: Интеграция с внешним API
Код: external-api-integration
Иконка: api-icon
JS URL: modules/external-api-integration/main.js
CSS URL: modules/external-api-integration/styles.css

После создания расширения и регистрации в системе лицензирования, расширение будет автоматически доступно компаниям, имеющим лицензию на это расширение.

Проверка подключения расширения

После создания записи расширения и обновления страницы в браузере проверьте подключение:

1. Откройте консоль браузера (F12)

2. Перейдите на вкладку Network (Сеть)

3. Обновите страницу (F5)

4. Проверьте запросы к файлам расширения:

   • Должны быть видны запросы к JavaScript файлам (указанным в поле JS URL)

   • Должны быть видны запросы к CSS файлам (указанным в поле CSS URL)

   • Статус запросов должен быть 200 OK (успешная загрузка)

5. Проверьте ответ сервера на запрос /auth/company:

   • В ответе должно быть поле extensions с массивом расширений

   • Ваше расширение должно присутствовать в массиве (если оно разрешено лицензией)

Если запросы к файлам отсутствуют или возвращают ошибки (404, 403 и т.д.), проверьте:

• Правильность путей в полях JS URL и CSS URL

• Доступность файлов по указанным адресам

• Права доступа к файлам на сервере

• Наличие лицензии на расширение для компании

Как обновить расширение?

Для обновления существующего расширения:

1. Откройте запись расширения в каталоге Расширения

2. Измените необходимые поля (название, иконка, URL файлов)

3. Сохраните изменения

Примечание:

• Изменение кода расширения может повлиять на доступность расширения для компаний, так как проверка лицензии выполняется по коду

• Изменение URL файлов применяется для всех компаний, имеющих доступ к расширению

• После обновления URL файлов может потребоваться обновление кэша браузера пользователей

Как удалить расширение?

Удаление расширения — операция, которая влияет на функциональность компаний, использующих это расширение.

Внимание: Перед удалением расширения убедитесь, что:

• Расширение не используется критически важными компаниями

• Удаление не нарушит работу системы

Как удалить расширение:

1. Откройте запись расширения в каталоге Расширения

2. Нажмите кнопку удаления записи

3. Подтвердите удаление

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

Технические детали

Структура данных расширения

Расширение в системе представлено следующими данными:

• code — уникальный код расширения (используется для идентификации и проверки лицензии)

• title — название расширения (отображается в интерфейсе)

• icon — класс иконки для отображения в меню

• js — массив URL JavaScript файлов (может быть многострочным текстом)

• css — массив URL CSS файлов (может быть многострочным текстом)

API для работы с расширениями

Система предоставляет API для получения расширений компании:

• Endpoint: /auth/company (при авторизации пользователя)

• Метод: GET

• Ответ: объект с полем extensions, содержащим массив доступных расширений:

  {
    "domain": "admin",
    "title": "Моя компания",
    "extensions": [
      {
        "code": "my-extension",
        "title": "Мое расширение",
        "icon": "my-icon",
        "js": ["modules/my-extension/main.js"],
        "css": ["modules/my-extension/styles.css"]
      }
    ]
  }

Расширения автоматически фильтруются по лицензии компании перед отправкой в веб-клиент. Сервер не вернет расширения, на которые не получена лицензия для компании.

Порядок загрузки расширений

Расширения загружаются в следующем порядке:

1. При авторизации пользователя система получает список доступных расширений

2. Веб-клиент инициализирует загрузку расширений через метод loadExtensions()

3. Для каждого расширения загружаются CSS файлы (если указаны)

4. Затем загружаются JavaScript файлы (если указаны)

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

Часто задаваемые вопросы

Почему расширение не загружается в веб-клиенте?

Если расширение не загружается в веб-клиенте, проверьте:

1. Регистрация расширения: убедитесь, что расширение зарегистрировано в системе лицензирования (см. раздел "Регистрация расширения")

2. Код расширения в лицензии: убедитесь, что код расширения добавлен в лицензию компании через сервер лицензирования разработчиков

3. Доступность файлов: проверьте, что файлы расширений доступны по указанным в полях JS URL и CSS URL адресам

4. Права доступа: убедитесь, что файлы расширений доступны для чтения веб-сервером

5. Кэш браузера: попробуйте очистить кэш браузера или выполнить жесткую перезагрузку страницы (Ctrl+Shift+R)

6. Консоль браузера: проверьте консоль браузера (F12) на наличие ошибок загрузки файлов

7. Сетевые запросы: проверьте вкладку Network в консоли браузера — должны быть запросы к файлам расширений со статусом 200 OK

Можно ли использовать внешние URL для расширений?

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

• Пример: https://cdn.example.com/extensions/my-extension.js

• Преимущества: не требуется хранить файлы на сервере Бипиум

• Ограничения: внешние ресурсы должны быть доступны по HTTPS и иметь правильные CORS заголовки

Важно: При использовании внешних URL убедитесь, что ресурсы доступны и имеют стабильные адреса. Изменение внешних URL может привести к недоступности расширения.

Можно ли изменить код расширения после создания?

Технически можно изменить код расширения, однако это повлияет на доступность расширения:

• Проблема: если код расширения изменен, лицензии компаний, которые ссылаются на старый код, перестанут работать

• Решение: перед изменением кода необходимо обновить все лицензии компаний, использующих это расширение, указав новый код

• Рекомендация: лучше создать новое расширение с новым кодом, чем изменять существующее

Как проверить, какие расширения доступны для компании?

Чтобы проверить доступные расширения для компании:

1. Войдите в систему от имени пользователя этой компании

2. Откройте консоль браузера (F12)

3. Перейдите на вкладку Network (Сеть)

4. Обновите страницу (F5)

5. Найдите запрос к /auth/company и откройте его

6. В ответе сервера проверьте поле extensions — там будет список доступных расширений для этой компании

7. Также проверьте сетевые запросы — должны быть запросы к файлам расширений (JS и CSS файлы)

Примечание: В ответе /auth/company будут только расширения, разрешенные лицензией компании. Расширения без лицензии не будут отображаться в списке.

Можно ли временно отключить расширение для компании?

Да, можно временно отключить расширение для компании:

1. Через каталог: удалите запись расширения из каталога Расширения (это отключит расширение для всех компаний)

2. Через лицензию: обратитесь к технической поддержке Бипиум для удаления кода расширения из лицензии компании (это отключит расширение только для конкретной компании)

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

Как обновить файлы расширения?

Для обновления файлов расширения:

1. Замените файлы расширения на сервере (если используются относительные пути)

2. Или обновите URL в поле JS URL или CSS URL (если используются внешние URL)

3. Сохраните изменения в записи расширения

4. Пользователям может потребоваться очистить кэш браузера или выполнить жесткую перезагрузку страницы

Совет: Используйте версионирование в URL файлов (например, /extensions/my-extension/v1.0.0/script.js) для контроля версий и обновлений расширений.

Как добавить расширение в лицензию компании?

ВАЖНО: Подключать сторонние и собственные расширения можно только в серверной версии Бипиум.

Сервер лицензирования находится у разработчиков Бипиум. Все проверки доступности расширений и добавление их в лицензии выполняются через сервер лицензирования платформы.

Для серверной версии процесс добавления расширения в лицензию компании:

1. Зарегистрируйте расширение в системе лицензирования (см. раздел "Регистрация расширения"):

   • Напишите письмо на [email protected]

   • Укажите выбранный уникальный код расширения

   • Укажите ваш регистрационный номер лицензии

2. Создайте расширение в каталоге (см. раздел "Как создать расширение?")

3. Разместите файлы расширения на сервере (см. раздел "Размещение файлов расширений")

4. Дождитесь подтверждения регистрации от технической поддержки Бипиум:

   • Разработчики Бипиум добавят код расширения в лицензию компании через сервер лицензирования

   • Лицензия будет обновлена с правильной цифровой подписью на сервере лицензирования

   • Ваша система автоматически загрузит обновленную лицензию при следующем обращении к серверу лицензирования разработчиков

КРИТИЧНО:

• Без регистрации расширения в системе лицензирования подключить его будет невозможно

• Лицензии имеют цифровую подпись, которая проверяется при загрузке

• Нельзя просто изменить лицензию в базе данных без правильной подписи — система не примет такую лицензию

• Для получения лицензии с правильной подписью необходимо обратиться к технической поддержке Бипиум через [email protected]

Связи с другими каталогами

Каталог Расширения связан с другими системными каталогами:

• Компании — доступность расширений для компаний определяется через лицензию компании. Подробнее см. в документации по каталогу Компании

Поддержка

Если у вас возникли вопросы или проблемы при работе с каталогом Расширения, обратитесь к технической поддержке Бипиум [email protected], предоставив:

• Версию Бипиум

• Лицензию (серийный номер)

• Описание проблемы или вопроса

• Код расширения

• Скриншоты

Дополнительные ресурсы

• Документация по каталогу Компании