Структура виджета

После того, как вы распакуете архив, вы увидете в корне файлы, PHP-библиотеки и папку widget_example, структуру которой мы рассмотрим:

FILEDESCRIPTION
manifest.jsonrequire Файл в формате json, содержащий описание виджета, настройки виджета, параметры виджета, выводимые пользователю, локализации с которыми работает виджет.
script.js JS-файл, который будет подключен на стороне пользователя в указанных в manifest.json областях
widget.php Необязательный файл, содержащий бизнес-логику на PHP, если необходимо. Хостинг php-скриптов на стороне amoCRM доступен только для публичных виджетов, доступных для всех пользователей amoCRM
images/ Папка для размещения файлов изображений, которые используются в виджете. Должна содержать в себе 3 файла (форматов png, jpeg, jpg или gif), которые будут использоваться как логотип виджета в разных областях видимости. Размер каждого файла не должен превышать 300 КБ.

logo.png используется на странице настроек виджетов, logo_min.png и logo_medium.png — во всех списках и карточках контактов или сделок в свернутом и развернутом состоянии соответственно.

Если у виджет стоит область видимости digital_pipeline, также необходимо изображение logo_dp.png, которое будет выводиться в настройках digital воронки


logo_dp.png174 x 109px

logo.png130px x 100px


logo_medium.png120px x 42px


logo_min.png42px x 42px
i18n/ Папка, содержащая файлы локализаций в формате ключ:значение. На текущий момент возможно использование только двух локализаций: русской (ru) и английской (en). Все переводы будут доступны как в JS, так и в PHP части

Как видите, обязательным является только файл manifest.json

4. Начинаем разработку

В качестве примера, мы возьмем виджет который основан только на JS. Он выводит кнопку в карточке контакта, при клике на которую данные из карточки отправляются во внешнюю систему, где для примера обрабатываются php-скриптом заглушкой, которая может быть написана на любом языке.

Это частая задача, т.к. часто требуется по бизнес процессу передавать данные из amoCRM по действию сотрудника во внутреннюю систему компании. Или наоборот выводить дополнительные данные из внешней системы в карточках amoCRM.

Кроме того, API amoCRM поддерживает событийную модель вызова сторонних скриптов через WebHooks-механизм. Он позволяет при определенных событиях, к примеру, изменение статуса сделки или изменение контакта, обращаться по указанному в настройках URL-скрипта и передавать в него актуальные данные. Подробнее о WebHooks читайте в соответствующем разделе.

Также, публичные виджеты могут взаимодействовать с функционалом digital воронок сделок и покупателей. Подробнее можно узнать в разделе виджеты в Digital pipeline

Итак, сначала копируем папку с примером виджета и называем ее widget. Это основа нашего будущего виджета.

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

5. manifest.json

Начинаем редактировать файл, руководствуясь таблицей описания его параметров. В значении вы можете использовать ссылку на языковые сообщения, если нужно.

PARAMETERDESCRIPTION
widget Блок содержит все основные настройки виджета
widget/name Название виджета, в том числе для отображения в списке виджетов. В примере, стоит значение widget.name, а это значит, что значение будет взято из соответствующего файла папки i18n, в зависимости от локализации. Если вы используете только один язык, то допускается сразу вводить название.
widget/description Полное описание виджета, показывается в окне настроек виджета. Вы можете использовать html-тэги, а также специальные short-теги для того, чтобы сформировать максимально персонифицированное описание. К примеру, вам нужно показать описание, подсказав пользователю субдомен аккаунта amoCRM в котором он работает. Список тэгов:
#HOST# - текущий хост;
#SUBDOMAIN# - субдомен аккаунта;
#LOGIN# - логин текущего пользователя, авторизованного пользователя;
#API_HASH# - хеш-ключ пользователя;
#ACCOUNT_ID# - id текущего аккаунта в системе;
#LINK#http://example.test/link_to_copy#/LINK# - тег данного вида преобразуется в поле и кнопку, при нажатии на которую скопируется ссылка;
#USER_ID# - id текущего пользователя в системе.
widget/short_description Короткое описание для вывода в списке виджетов
widget/code То что вы ввели латинскими символами при генерации ключа на странице разработчика. Ваш код виджета
widget/secret_key Секретный ключ виджета, который вы сгенерировали на странице разработчика
widget/version Версия виджета. Носит только информативную нагрузку.
widget/interface_version (int) Версия интерфейса (1,2) для какого именно интерфейса системы загружается виджет. По умолчанию необходимо оставлять 2. Интерфейс 1 — предыдущая версия интерфейса всей системы amoCRM, без использования AJAX. Регистрация на старую версию сейчас закрыта.
widget/init_once (true/false) указание нужно ли собирать js объект виджет 1 раз за сеанс работы с интерфейсом amocrm. При инициализации виджета вызываются функции render(), init() и bind_actions() (подробнее о них в части script.js). Указание true или false регулирует возможность каждый раз при переходе из области в область (подробнее об областях подключения) вызывать функции init() и bind_actions(), или вызвать их только один раз. К примеру, виджеты телефоний постоянно удерживают WebSocket соединение и его обрыва происходить не должно, поэтому init_once должно иметь значение true. Если же общего для всех страниц контекста нет, то лучше ставить в false.
widget/locale Массив локализаций, на которых доступен виджет. Для публикации виджета на английском должна осуществляться поддержка на английском языке со стороны разработчика.
widget/installation (true/false) Если выбрано false, то виджет будет только отображаться в списке виджетов, не запрашивая настройки или установка в аккаунте. Это актуально, когда все настройки происходят в другой системе, взаимодействующей с amoCRM через API.
locations Интерфейсы в которых должен быть отображен виджет. Массив, обязательный для заполнения, в случае если необходимо использовать js часть виджета. Подробнее об областях.
Возможные местоположения:
llist — список сделок, clist — список контактов, tlist — список задач, lcard — карточка сделки, ccard — карточка контакта, card_sdk — SDK карточки, culist - cписок покупателей, cucard - карточка покупателя, digital_pipeline - digital воронка сделок и покупателей.

Так же необходимо сообщить нашей системе будет ли виджет использовать правую колонку для отображения, сделать это можно дописанием 0 или 1 после указания зоны

То есть, если указать "clist-0", виджет инициализируется в данной зоне, но не будет использовать правую колонку.

К примеру, панель для WEB-фона находится не в правой колонке виджетов, а внизу в любом интерфейсе. Поэтому для всех мест подключения в настройках виджета должно быть написано 0, но при этом на каждой странице он инициализируется.

settings Массив настроек виджета, доступных пользователю, т.е. поля, которые будут присутствовать в окне настроек виджета и заполняться пользователем. Данный раздел требуется только если installation = true, если installation = false, то данный раздел не нужен, т.к. в окне настроек будет выводиться только описание виджета.Ключем в массиве является код поля FIELD_CODE
settings/FIELD_CODE/name Название поля (только ссылка на элемент в lang файле)
settings/FIELD_CODE/type Тип поля. Доступные варианты:
  • text
  • pass
  • users(список пользователей системы с 1 текстовым полем на каждого, требуется в случае если нужно ввести какую-то информацию по каждому сотруднику, например внутренний телефонный номер для IP-телефонии)
  • users_lp (список пользователей системы с 2 полями (login,password) на каждого.

Подробно типы полей разобраны в разделе Типы полей раздела settings manifest.json

settings/FIELD_CODE/required true/false обязательность заполнения поля пользователем.
dp Блок настройки виджетов в digital pipeline.
Данный блок необходимо включать в manifest.json, только если есть область видимости digital_pipeline.
С функционалом digital pipeline могут работать только публичные виджеты, имеющие файл widget.php, в котором пристуствует endpoint digital_pipeline (подробнее Digital pipeline)
dp/settings/ Аналогичен блоку settings, но будет выводится при настройке виджета в digital воронке.
dp/settings/action_multiple Обязательное поле в блоке dp, значения - true/false, определяет, может ли действие виджета растягиваться на несколько этапов

Пример manifest.json

  1. {
  2. "widget":{
  3.   "name": "widget.name",
  4.   "description": "widget.description",
  5.   "short_description": "widget.short_description",
  6.   "code": "new_widget",
  7.   "secret_key": "57009cb5048a72191f25b01355c17d10dc349df20d4fe2ad0c69930223e13955",
  8.   "version": "1.0.0",
  9.   "interface_version" : 2,
  10.   "init_once" : false,
  11.   "locale":[
  12.         "ru",
  13.         "en"
  14.         ],
  15.     "installation": true
  16.     },
  17. "locations":[
  18.     "ccard-1",
  19.     "clist-1",
  20.     "digital_pipeline",
  21.     "settings"
  22.     ],
  23. "settings":{
  24.     "login":{
  25.         "name": "settings.login", //указывает на файл локализации, в папке i18n
  26.         "type": "text", //тип: текстовое поле
  27.         "required": false
  28.         },
  29.     "password":{
  30.         "name": "settings.password",//указывает на файл локализации, в папке i18n
  31.         "type": "pass", //тип: пароль
  32.         "required": false
  33.         }
  34.   },
  35.   "dp": {
  36.     "settings": {
  37.         "message": {
  38.             "name": "settings.message",
  39.             "type": "text",
  40.             "required": true
  41.         }
  42.     },
  43.     "action_multiple": false
  44.   }
  45. }

6. i18n Файлы локализации

Как вы уже могли заметить в примере manifest.json используются конструкции вида widget.name. Они необходимы, если ваш виджет должен работать более, чем на одном языке.

В таком случае необходимо создать в папке i18n два файла локализации для русского и английского языка ru.json и en.json. После чего, в зависимости от языка аккаунта как в JS части, так и в PHP будут доступны языковые сообщения на соответствующем языке.

ВАЖНО: Если используется 2 локализации, то необходимо, чтобы файлы были одинаковыми по структуре.

i18n/ru.json

  1. {
  2.     "widget": {
  3.         "name": "Demo виджет",
  4.         "short_description": "Виджет для отсылки контакта во внутреннюю систему",
  5.         "description": "Виджет, который служит для отправки данных из карточки контакта вашего домена #SUBDOMAIN# во внутренню систему"
  6.     },
  7.     "settings": {
  8.         "login": "Логин",
  9.         "password": "Пароль"
  10.   },
  11.  
  12.     "userLang": {
  13.         "firstWidgetText": "Кликните на кнопку, чтобы переслать данные на сторонний сервер:",
  14.         "textIntoTheButton": "Отправить данные",
  15.     "responseMessage" : "Ответ сервера :",
  16.     "responseError" : "Ошибка"
  17.     }
  18. }

i18n/en.json

  1. {
  2.     "widget": {
  3.         "name": "Demo widget",
  4.         "short_description": "Widget for sending the contact to the internal system",
  5.         "description": "Widget that is used to send data from the contact card on your domain # SUBDOMAIN # in the internal system"
  6.     },
  7.     "settings": {
  8.         "login": "Login",
  9.         "password": "Password"
  10.     },
  11.    "userLang": {
  12.         "firstWidgetText": "Please, click on the button, if you want:",
  13.         "textIntoTheButton": "Send Data",
  14.     "responseMessage" : "Server response:",
  15.     "responseError" : "Failed"
  16.     }
  17. }

Для обращения к языковым сообщениям из JS кода виджета используйте метод self.i18n('obj_name'), где obj_name - это один из объектов файла локализации.

Примеры файлов manifest.json есть в разделе Типы полей раздела settings manifest.json

Типовые ошибки

  • Т.к. многие файлы, в частности manifest.json имеют формат json, то лучше перед их загрузкой убеждаться в корректности синтаксиса используя онлайн проверки json файлов. Одной из самых частых ошибок является загрузка файла с некорректным синтаксисом
  • Кодировка — все файлы должны быть в кодировке UTF-8 без BOM
  • Уже перед первой загрузкой виджета в манифесте необходимо заменить код и ключ из сказанного примера на сгенерированные вами уникальные
  • Зачастую в упакованном архиве в корне лежит папка widget, как первый уровень, а на самом деле должны уже сразу лежать файлы
  • Если изначально был загружен неверный manifest, то необходимо сгенерировать новый код и ключ, т.к. предыдущий будет дескредитирован
Next Step: Script JS