Любое расширение в laxo – это один или несколько ZIP-архивов, состоящих из определенного набора файлов (состав зависит от вида расширения).
В этом разделе рассматриваются два вида расширения: клиентское и клиентско-серверное. Обычные серверные расширения размещаются на мощностях разработчика и могут иметь любую структуру.
Файловая
структура расширения
Клиентские расширения состоят из одного ZIP-архива, а клиентско-серверные – из двух архивов отдельно для каждой части. Состав каждого архива:
| ОСНОВНОЙ ZIP-АРХИВ (для клиентских расширений / для клиентской части) | |
|---|---|
| Файл | Назначение |
config.js * | Конфигурационный файл расширения. Содержит сведения о расширении, страницы и обработчики интерфейса. Обязательный файл, без которого расширение не может быть установлено. |
icon.png * | Иконка расширения. Обязательный файл, но имя может быть любым (указывается в config.js). |
settings.html, ... | Страницы настроек, особые скрипты и стили, иные медиафайлы, которые нужны для работы расширения. Необязательно. |
README.txt | Описание расширения, инструкция по установке, настройке и использованию. Внутренний сопроводительный документ для других разработчиков или модератора. Необязательно для частного расширения. |
EVALS.md | Сценарии проверки, которые можно использовать при тестировании и модерации. Необязательно для частного расширения. |
AGENTS.md | Контекст для AI-агентов, которые будут дорабатывать расширение. Необязательно. |
| ДОПОЛНИТЕЛЬНЫЙ ZIP-АРХИВ (для клиентско-серверных расширений / для серверной части) | |
|---|---|
| Файл | Назначение |
Dockerfile * | Набор инструкций для создания образа с серверной частью расширения, который будет вызван при установке. Обязательный файл. |
/sessions/ | Директория для хранения любых постоянных данных расширения. Подробная информация представлена в разделе Файлы серверной части. |
... | Программный код и иные файлы расширения. |
Важно: названия обязательных файлов чувствительны к регистру.
Конфигурационный
файл
Это главный файл расширения, который представляет собой JavaScript-объект. Он описывает общие сведения о расширении и задает все основные его параметры.
| Ключ | Назначение |
|---|---|
name * | Идентификатор расширения. Формат: ${crm_name}_${ext_name}, где crm_name — имя аккаунта разработчика, а ext_name — выбранное имя расширения. |
view_name * | Публичное название расширения, которое видят пользователи. |
description * | Краткое текстовое описание расширения. |
full_description * | Подробное описание расширения (поддерживаются HTML-теги). |
ava_image * | Путь к иконке расширения. Указывается относительный путь до иконки от корня архива. |
image_gallery * | Массив изображений работы расширения для галереи. Указываются относительные пути от корня архива до изображения. Массив может быть пустым, если наличие изображений не предполагается. |
developer_data * | Информация о разработчике. |
categories * | Категория расширения для отображения в каталоге: 0 – Популярное, 1 – Общение, 2 – Маркетинг и рассылки, 3 – Звонки, 4 – Сбор заявок, 5 – Автоматизация. |
tags * | Информационные теги (метки) расширения. Массив может быть пустым, если теги не предполагаются. |
price * | Стоимость расширения (строка). Значение 0 означает бесплатное распространение. |
pay_period * | Периодичность оплаты. Значение onetime задает разовую оплату при первой установке (указывается в том числе для бесплатных расширений), а значение month – для регулярных ежемесячных списаний. |
init * | Объект с описанием методов взаимодействия с интерфейсом и событиями. |
Лучше всего работать с конфигурационным файлом через AI-навык или специальный образец, в котором приведены дополнительные комментарии и примеры использования различных параметров. Заполните ключи данными для вашего расширения и удалите демонстрационные элементы, которые не планируется использовать.
Взаимодействие
с интерфейсом и событиями
Взаимодействие с элементами CRM задается в специальных ключах объекта init в конфигурационном файле. Ни один из ключей не является обязательным.
| Ключ | Назначение |
|---|---|
extensionPage | Список собственных страниц расширения, например страницы настроек. |
settingBtn | Список кнопок, которые могут отображаться на странице расширения, например кнопка перехода к настройкам. |
addUserSetting | Персональные настройки пользователей CRM. |
additionalActions | Действия в меню дополнительных действий (списки, карточки задачи, контактов или сделок). Подробнее в разделе Поддерживаемые списки действий и событий. |
additionalEvents | Обработчики событий в чатах карточек. |
fieldEvents | Обработчики расширения при нажатии на какое-либо дополнительное поле. |
mountedPage | Код, выполняемый при открытии конкретной страницы CRM. |
mountedApp | Код, выполняемый после построения приложения, например при открытии или перезагрузке вкладки с CRM. Переход между страницами не запускает mountedApp заново. |
hooksToAdd | Обработчики событий клиентского интерфейса. |
nativeInit | Код, выполняемый после включения расширения. |
Каждый ключ имеет свои параметры, подробная информация о которых представлена в специальном образце конфигурационного файла, где приведены дополнительные комментарии. Среди параметров можно особо выделить два: target и functionName. В target указывается действие или событие, при котором должен вызываться обработчик расширения (Поддерживаемые списки действий и событий). Обработчик задается в functionName как автономная функция, в которую данные о событии или объекте передаются в аргументе obj (список значений obj).
Примеры взаимодействия и лучшие практики можно найти в рекомендациях по разработке.
Поддерживаемые
списки действий и событий
Для additionalActions, additionalEvents, mountedPage, fieldEvents:
ContactList– список контактовContactView– карточка просмотра контактаOrderList– список сделокOrderView– карточка просмотра сделкиJobList– список задачJobView– карточка просмотра задачи
Дополнительно только для mountedPage, fieldEvents:
ContactsAdd– карточка создания контактаContactsEdit– карточка редактирования контактаOrderAdd– карточка создания сделкиOrderEdit– карточка редактирования сделки
Дополнительно только для mountedPage:
ContactMassEdit– страница массового редактирования контактовOrderMassEdit– страница массового редактирования сделокJobAdd– карточка создания задачиJobEdit– карточка редактирования задачиFunnelAdd– страница создания воронкиFunnelUpdate– страница редактирования воронкиSendMess– страница массовой отправки emailReports– страница со списком всех видов отчетовReportsDeals– страница отчета по сделкамReportsSales– страница отчета по продажамReportsContacts– страница отчета по контрагентамReportsWorkers– страница отчета по сотрудникамReportsContrs– страница отчета по контрагентамReportsUsersLog– страница отчета по действиям сотрудников
Для одного и того же
targetможно добавлять несколько кнопок с разнымorder: они выстроятся в меню по возрастаниюorder.
Список хуков (событий), к которым можно привязать обработчики расширения:
window.Laxo.Order.addOrder– сохранение/добавление сделкиwindow.Laxo.Order.changeOrder– изменение сделки, включая отметку на удалениеwindow.Laxo.Order.deleteOrder– полное удаление сделкиwindow.Laxo.Order.getOrderList– получение списка сделокwindow.Laxo.Order.getOrderOne– получение одной сделкиwindow.Laxo.Contact.addContact– сохранение/добавление контактаwindow.Laxo.Contact.changeContact– изменение контакта, включая отметку на удалениеwindow.Laxo.Contact.deleteContact– полное удаление контактаwindow.Laxo.Contact.getContactList– получение списка контактовwindow.Laxo.Contact.getContactOne– получение одного контактаwindow.Laxo.Job.addJob– сохранение/добавление задачиwindow.Laxo.Job.changeJob– изменение задачи, включая отметку на удалениеwindow.Laxo.Job.setJobResult– добавление результата задачи пользователемwindow.Laxo.Job.getJobList– получение списка задачwindow.Laxo.Message.sendMessage– отправка сообщенияwindow.Laxo.Message.deleteMessage– удаление сообщенияwindow.Laxo.Message.multipleSendMessage– массовая отправка email
Собственные
страницы и ресурсы
Расширение может создавать свои собственные страницы, которые будут добавлены в интерфейс laxo CRM, например страницы настроек. Страницы создаются как обычные HTML-файлы, которые могут подключать свои стили, скрипты и медиа. Страницы описываются в массиве init.extensionPage в конфигурационном файле и доступны по адресу:
https://${crm_name}.laxo.one/ext/${ext_name}/${html_file}${crm_name}– адрес аккаунта CRM (домен).${ext_name}– идентификатор расширения.${html_file}– имя файла собственной страницы.
Ограничения на количество страниц и дополнительных ресурсов отсутствуют.
Для лучшего пользовательского опыта рекомендуется соблюдать требования к фирменному стилю laxo и UI, которые приведены в рекомендациях по разработке. Эти критерии являются обязательными для публичных расширений. Легко адаптировать интерфейс под требования можно с помощью AI-навыка.
Файлы
серверной части
Для клиентско-серверных расширений серверная часть упаковывается отдельно. В архив должны входить Dockerfile и исходные файлы приложения.
Обратите внимание, что самостоятельное серверное расширение размещается на выбранных разработчиком мощностях и может иметь другую структуру. Описываемые далее требования относятся к публичным клиентско-серверным расширениям, размещаемым на серверах laxo.
В момент установки расширения создается контейнер с данными расширения, который доступен для взаимодействия через специализированный прокси (Docker proxy):
curl -X POST "https://${crm_name}.laxo.one/docker/proxy/${ext_name}/" \
-H "sid: ${sid}" \
-d ''
# ${ext_name} - идентификатор Расширения (задается в КФР)
# ${sid} - идентификатор сессии обычного пользователя или СП (см. раздел `Получение SID для Backend` далее)
# По ${sid} Docker proxy определяет пользователя и вместо sid передает далее в сам backend заголовки:
# x-crm-name - Имя (домен) аккаунта.
# user_id - ID пользователя.curl -X POST "https://${crm_name}.laxo.one/docker/proxy/${ext_name}/webhook/" \
-d ''
# ${ext_name} - идентификатор Расширения (задается в КФР)Важно:
Docker Proxyзапускает контейнер и пробрасывает внешний динамический порт на8080. Поэтому приложение внутри контейнера должно принимать HTTP именно на8080.
Архитектура расширения должна учитывать, что один контейнер обслуживает все аккаунты, которым доступно расширение. Постоянные данные расширения должны храниться в специальном корневом каталоге /sessions/, который монтируется как Docker volume и сохраняется при перезапуске контейнера (он может быть перезагружен автоматически, например при зависании).
Серверная часть должна поддерживать как минимум два endpoint: GET /start и GET /stop , которые вызываются при подключении и отключении расширения.
Больше информации о примерах использования, лучших практиках и требованиях к оформлению расширений можно найти в рекомендациях по разработке.