Примеры JS-модулей для RetailCRM / Simla.com.

Документация по разработке JS-модулей.

Описание примеров

Во всех примерах используется библиотека vue-i18n и тексты компонентов выводятся на языке системы. В разрабатываемых модулях требуется использовать тот же подход, подготавливая переводы на русском, английском и испанском.

1. Кнопки перехода в мессенджеры cases/customerPhone

Пример позволяет добавить рядом с номером телефона клиента на странице заказа и клиента кнопки перехода в мессенджеры по этому номеру.

В данном примере можно увидеть, как встраивать модуль в таргеты с разным контекстом и корректно читать данные из него.

2. Чеки в блоке Оплата cases/fiscalReceipts

Данный пример:

• выводит кнопку «Фискальные чеки» в блоке «Оплата»
• подтягивает с бекенда модуля количество чеков, выбитых по заказу, и показывает в кнопке
• по нажатию на кнопку открывает шторку, в которой загружается с бекенда модуля и отображается перечень чеков с их детализацией

По данному примеру можно понять, как взаимодействовать с бекендом модуля и отображать данные из сторонней системы в шторке. Также в примере можно увидеть обработку ответа на http-вызов к бекенду и вывод ошибки. Кроме того в примере показано, как передавать данные заказа в http-вызове и обрабатывать на стороне бекенда.

Данный пример полноценно работает при регистрации в виде интеграционного модуля.

3. Адрес на карте cases/yandexMap

Пример представляет собой модальное окно с интерактивной картой от Яндекса. Маркер можно перетаскивать и тем самым изменять адрес. Используется JavaScript API Яндекс Карт и Геокодер версии 3.0. При первоначальной отрисовке позиционирование маркера происходит исходя из адреса в поле "Адрес" заказа. Далее при перетаскивании маркера адрес выбирается исходя из текущих координат маркера, выбирается ближайший адрес к текущим координатам.

В данном примере можно понять, как выводить модальные окна с дополнительной информацией и применять к полю в форме данные, выбранные в модальном окне.

4. Кнопка рядом с полем Телефон в заказе cases/phoneReactive

Пример выводит кнопку рядом с полем телефона в заказе.

В примере видно, как надпись на кнопке реактивно меняется в зависимости от введенного номера телефона. По клику на кнопку в поле Телефон подставляется некоторое значение и система подсвечивает измененное поле.

5. Добавление элементов во всех target-ы страницы заказа cases/allTargetsButton

Данный модуль выводить кнопки и ссылки во всех доступных target-ах страницы заказа.

Пример помогает увидеть все доступные места встраивания страницы заказа. Реакция на клик для кнопок и ссылок не предусмотрена.

6. Запись клиента на встречу через Calendly cases/recordToCalendly

Модуль выводить кнопку «Записать на встречу» в блоке Клиент карточки заказа. По клику на кнопку открывается модальное окно с виджетом Calendly, встроенном через iframe, в котором можно выбрать время и дату встречи. На последнем шаге виджета в поле Name и Email подставляются данные блока Клиент.

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

7. Заметки к заказу cases/orderNotes

Модуль выводить кнопку «Заметки к заказу» в блоке Основное карточки заказа. По клику на кнопку открывается боковая панель с ранее внесенными заметками к заказу и формой отправки новой заметки. При отправке заметки фиксируется id заказа, к которому привязана новая заметка, а также фамилия и имя пользователя, который ее оставил.

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

Данный пример полноценно работает при регистрации в виде интеграционного модуля.

8. Поиск реквизитов по ИНН cases/customerINN

Модуль отслеживает изменения в поле company.INN и опрашивает backend на предмет наличия информации о компании по INN. Если информация найдена, то появляется кнопка "Дополнить из компании <Компания>", по клику на которую все поля реквизитов заполняются найденной информацией, и кнопка скрывается.

Пример демонстрационный, информация находится, если ввести ИНН "1234567890".

Данный пример полноценно работает при регистрации в виде интеграционного модуля.

9. Просмотр пользовательских полей cases/customFieldViewer

Модуль получает данные по пользовательским полям заказа, позволяет выбрать поле с помощью группы радио-кнопок и просмотреть его значение. Также можно изменить значение поля, если он редактируемое.

Запуск

Начальное развертывание

Установка зависимостей

yarn install

Сборка приложения

yarn build

Для инициализации приложения внутри CRM необходимо выполнить его сборку (yarn build), а затем предоставить html страницу с подключенными скриптами сборки в качестве значения entrypoint, а так же файл стилей в качестве значения stylesheet объекта конфигурации.

В данном примере есть файл сервера, который отдает необходимые ресурсы и endpoint-ы для обработки HTTP-вызовов. После сборки приложения достаточно его запустить с помощью команды node server.mjs.

После этого, на странице заказа в CRM достаточно вызвать в консоли браузера, чтобы инициализировать один из модулей выше (порядок сохранен):

// customerPhone
window['CRM'].embed.register({
  "uuid": "a796ad7e-55e8-4653-b328-51a953c4cb18",
  "targets": [
    "customer/card:phone",
    "order/card:customer.phone"
  ],
  "entrypoint": "http://localhost:3000/extension/a796ad7e-55e8-4653-b328-51a953c4cb18",
  "stylesheet": "http://localhost:3000/extension/a796ad7e-55e8-4653-b328-51a953c4cb18/stylesheet"
})

// fiscalReceipts
window['CRM'].embed.register({
  "uuid": "db275ab4-9f7e-405d-89a1-f6d56625db7a",
  "targets": [
    "order/card:payment.before",
  ],
  "entrypoint": "http://localhost:3000/extension/db275ab4-9f7e-405d-89a1-f6d56625db7a",
  "stylesheet": "http://localhost:3000/extension/db275ab4-9f7e-405d-89a1-f6d56625db7a/stylesheet"
})

// yandexMap
window['CRM'].embed.register({
    "uuid": "62aa8145-ed53-4862-b28f-f1bc6b36a3a3",
    "targets": [
        "order/card:delivery.address"
    ],
    "entrypoint": "http://localhost:3000/extension/62aa8145-ed53-4862-b28f-f1bc6b36a3a3",
    "stylesheet": "http://localhost:3000/extension/62aa8145-ed53-4862-b28f-f1bc6b36a3a3/stylesheet"
})

// phoneReactive
window['CRM'].embed.register({
    "uuid": "930ab49c-f6a2-4407-b64b-54ffe4c785a2",
    "targets": [
        "order/card:customer.phone"
    ],
    "entrypoint": "http://localhost:3000/extension/930ab49c-f6a2-4407-b64b-54ffe4c785a2"
})

// allTargetsButton
window['CRM'].embed.register({
    "uuid": "30ff05b5-4473-4b41-a910-1428cc13394e",
    "targets": [
        "order/card:common.before",
        "order/card:common.after",
        "order/card:customer.before",
        "order/card:customer.after",
        "order/card:customer.email",
        "order/card:customer.phone",
        "order/card:list.before",
        "order/card:list.after",
        "order/card:store.before",
        "order/card:dimensions.before",
        "order/card:dimensions.before",
        "order/card:delivery.before",
        "order/card:delivery.after",
        "order/card:delivery.address",
        "order/card:payment.before",
        "order/card:comment.manager.before"
    ],
    "entrypoint": "http://localhost:3000/extension/30ff05b5-4473-4b41-a910-1428cc13394e"
})

// recordToCalendly
window['CRM'].embed.register({
    "uuid": "d3301ba9-cca9-46c2-b097-b404419b64ce",
    "targets": [
        "order/card:customer.after"
    ],
    "entrypoint": "http://localhost:3000/extension/d3301ba9-cca9-46c2-b097-b404419b64ce"
})

// orderNotes
window['CRM'].embed.register({
    "uuid": "2f34c0a1-7004-4c57-831b-7269ac2b257c",
    "targets": [
        "order/card:common.before"
    ],
    "entrypoint": "https://localhost:3000/extension/2f34c0a1-7004-4c57-831b-7269ac2b257c",
    "stylesheet": "https://localhost:3000/extension/2f34c0a1-7004-4c57-831b-7269ac2b257c/stylesheet"
})

// customerINN
window['CRM'].embed.register({
    "uuid": "c212cb60-5650-433a-82db-09f0f604056a",
    "targets": [
        "order/card:customer.after"
    ],
    "entrypoint": "https://localhost:3000/extension/c212cb60-5650-433a-82db-09f0f604056a"
})

// customFieldViewer
window['CRM'].embed.register({
  "uuid": "dca0afa1-f765-442a-8958-01230d87098f",
  "targets": [
    "order/card:common.after"
  ],
  "entrypoint": "https://localhost:3000/extension/dca0afa1-f765-442a-8958-01230d87098f",
  "stylesheet": "https://localhost:3000/extension/dca0afa1-f765-442a-8958-01230d87098f/stylesheet"
})

Регистрация как интеграционного модуля в аккаунте RetailCRM

Собрав модуль, вы можете инициализировать его не через консоль браузера, а как интеграционный модуль в аккаунте RetailCRM.

Для этого вам необходимо внести информацию о модуле в файл cases.json:

• uuid — уникальный идентификатор модуля (произвольный)
• name — символьный код модуля (должен соответствовать названию папки сборки модуля в dist/)
• targets — точки встраивания
• entrypoint — относительный путь к js-файлу, как указано в ключе dist/manifest.json
• stylesheet — относительный путь к css-файлу, как указано в ключе dist/manifest.json, если у модуля есть стили

После чего выполнить:

make register

При вызове команды make register требуется интерактивно указать:

• адрес аккаунта RetailCRM, например https://demo.retailcrm.ru
• API-ключ для работы с REST API аккаунта
• название модуля (как указано в cases.json), например yandexMap
• базовый адрес модуля, например https://my-module.tech — это может быть адрес прокси (аля ngrok), который проксирует запросы на ваш локальный сервер

Сборка архива

Перед сборкой архива выполните сборку модуля с помощью make build или yarn build.

После этого выполните:

make zip-archive

При вызове команды make zip-archive требуется интерактивно указать:

• название папки со сборкой модуля из dist/
• версию модуля
• список target-ов, в которые будет встраиваться модуль, через запятую

На снове введенных данных будет сгенерирован manifest.json и создан архив с модулем в папке dist/.