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

Любое расширение в 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Код, выполняемый после включения расширения.
Возможные ключи для описания способов взаимодействия с CRM

Каждый ключ имеет свои параметры, подробная информация о которых представлена в специальном образце конфигурационного файла, где приведены дополнительные комментарии. Среди параметров можно особо выделить два: 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 – страница массовой отправки email
  • Reports – страница со списком всех видов отчетов
  • 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 , которые вызываются при подключении и отключении расширения.

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

Остались вопросы? Спросите в чате! В нашем сообществе в Telegram можно быстро задать вопрос, получить подсказку от команды Laxo или обменяться опытом с другими пользователями.