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

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

Файл Описание
manifest.json Файл в формате json, содержащий описание виджета, настройки виджета, параметры виджета, выводимые пользователю, локализации, с которыми работает виджет. (обязательный файл)
script.js JS-файл, который будет подключен на стороне пользователя в указанных в manifest.json областях (обязательный файл)
images/ Папка для размещения файлов изображений, которые используются в виджете. Должна содержать в себе 5 файлов в формате (png, jpeg,jpg или gif), которые будут использоваться как логотип виджета в разных областях видимости. Размер каждого файла не должен превышать 300 КБ. logo_min.png и logo_medium.png — обязательно, если виджет работает в карточках, используется во всех списках и карточках контактов или сделок в свернутом и развернутом состоянии соответственно. Изображения logo_main и logo_small дублируют цели logo_min соответственно, обязательны к отгрузке с ноября 2018 года. Также необходимо загрузить logo.png для поддержки старых версий.
i18n/ Папка, содержащая файлы локализаций в формате ключ:значение. На текущий момент возможно использование нескольких локализаций: русской(ru), английской(en), португальской(pt), испанской(es). Все переводы будут доступны в JS.

В папке images/ должны быть файлы с размерами:

logo_main.png 400px x 272px
logo_small.png 108px x 108px
logo.png 130px x 100px
logo_medium.png 240px x 84px
logo_min.png 84px x 84px
logo_dp.png 174px x 109px

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

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

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

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

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

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

manifest.json

Начинаем редактировать файл, руководствуясь таблицей описания его параметров. В значении вы можете использовать ссылку на языковые сообщения, если нужно. Внимание! С ноября 2018 года добавилось 2 ОБЯЗАТЕЛЬНЫХ поля в manifest.json. Поля отвечают за обратную связь и располагаются в кнопке "Обратная связь" (необходимо указать ссылку на сайт поддержки, либо email). Обратите внимание, email является менее приоритетным способом связи. Краткое описание виджета будет располагаться в левой части модального окна. С ноября 2019 года добавлено ОБЯЗАТЕЛЬНОЕ свойство в manifest.json – тур (tour). Тур — это набор картинок, на которых демонстрируется функционал виджета. Обязательными поля данного свойства являются: поле с указанием включением тура для виджета, ключи локализаций для картинок тура и ключ ланга, содержащего краткий текст, который будет выведен в момент показа тура виджета. Подробнее можно узнать в статье.

Параметр Описание
widget Блок содержит все основные настройки виджета
widget/name Обязательное поле. Название виджета, в том числе для отображения в списке виджетов. Должно содержать путь к переводу в языковых файлах. В примере стоит значение widget.name, а это значит, что значение будет взято из соответствующего файла папки i18n, в зависимости от локализации.Если виджет загружен в разделе amoМаркет => Мое приложение, то будет использоваться описание, указанное в интеграции, при этом поле пока что остается обязательным.
widget/description Обязательное поле. Полное описание виджета, показывается в окне настроек виджета. Должно содержать путь к переводу в языковых файлах. Вы можете использовать html-тэги, а также специальные short-теги для того, чтобы сформировать максимально персонифицированное описание. К примеру, вам нужно показать описание, подсказав пользователю субдомен аккаунта amoCRM в котором он работает. Список доступных тэгов: #HOST#– текущий хост; #SUBDOMAIN#– субдомен аккаунта; #LOGIN#– логин текущего пользователя, авторизованного пользователя; #API_HASH# – хеш-ключ пользователя; #ACCOUNT_ID# – id текущего аккаунта в системе; #USER_ID#– id текущего пользователя в системе, #TOP_LEVEL_DOMAIN# – домен верхнего уровня (com или ru) Если виджет загружен в разделе amoМаркет => Мое приложение, то будет использоваться описание, указанное в интеграции, при этом поле пока что остается обязательным.
widget/short_description Обязательное поле. Короткое описание для вывода в списке виджетов. Должно содержать путь к переводу в языковых файлах.
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 Обязательное поле c массивом кодов языков, на которых будет доступен виджет. Под каждый язык должен быть свой файл с переводом в папке i18n. Доступные языки: ru, en, es (русский, английский и испанский соответственно).Если виджет загружен в разделе amoМаркет => Мое приложение, то языковые файлы должны совпадать с теми языками, которые заполнены в интеграции.
widget/installation (true/false) Если выбрано false, то виджет будет отображаться только в списке виджетов, не запрашивая настройки или установку в аккаунте. Это актуально, когда все настройки происходят в другой системе, взаимодействующей с amoCRM через API.
widget/is_showcase (true/false) True изменяет название кнопки "Установить" на "Посмотреть". Это необходимо, когда виджет носит информационный характер, не устанавливается напрямую. installation при этом должен быть false.
locations Интерфейсы в которых должен быть отображен виджет. Массив, обязательный для заполнения, в случае если необходимо использовать js часть виджета. Подробнее об областях. Возможные местоположения: llist — список сделок, clist — список контактов, tlist — список задач, lcard — карточка сделки, ccard — карточка контакта, card_sdk — SDK карточки, culist – cписок покупателей, cucard – карточка покупателя, digital_pipeline – digital воронка сделок и покупателей, catalogs – SDK списков, whatsapp_modal – модальное окно интеграций, работающих с WhatsApp, advanced_settings – страница расширенных настроек виджета, salesbot_designer – возможность использовать виджет в конструкторе Salesbot, sms –возможность отправки системных SMS виджетом, mobile_card – возможность использования виджета в мобильных приложениях. Так же необходимо сообщить нашей системе будет ли виджет использовать правую колонку для отображения, сделать это можно дописанием 0 или 1 после указания зоны. То есть, если указать "clist-0", виджет инициализируется в данной зоне, но не будет использовать правую колонку. К примеру, панель для WEB-фона находится не в правой колонке виджетов, а внизу в любом интерфейсе. Поэтому для всех мест подключения в настройках виджета должно быть написано 0, но при этом на каждой странице он инициализируется. amoforms – возможность использования виджета в веб-формах.
tour Блок содержит все основные настройки для тура виджета. Пример реализации можете посмотреть ниже
tour/is_tour (true/false) указывает на то, нужно ли включать тур для виджета. false на данный момент является depricated. Значение всегда должно быть true
tour/tour_images Содержит ключи локализаций для картинок тура
tour/tour_images/{lang} (Array) Содержит путь до изображений для тура в зависимости от локализации
tour/tour_description Ключ ланга, содержащего краткий текст, который будет выведен в момент показа тура виджета
settings Массив настроек виджета, доступных пользователю, т.е. поля, которые будут присутствовать в окне настроек виджета и заполняться пользователем. Данный раздел требуется только если installation = true, если installation = false, то данный раздел не нужен, т.к. в окне настроек будет выводиться только описание виджета.Ключем в массиве является код поля {FIELD_CODE}
settings/{FIELD_CODE}/name Название поля (только ссылка на элемент в lang файле)
settings/{FIELD_CODE}/type Тип поля. Доступные варианты: a) text, b) pass, c) users (список пользователей системы с 1 текстовым полем на каждого, требуется в случае если нужно ввести какую-то информацию по каждому сотруднику, например внутренний телефонный номер для IP-телефонии), d) users_lp (список пользователей системы с 2 полями (login,password) на каждого. Подробно типы полей разобраны в разделе Типы полей раздела settings manifest.json
settings/{FIELD_CODE}/required true/false обязательность заполнения поля пользователем.
dp Блок настройки виджетов в digital pipeline. Данный блок необходимо включать в manifest.json, только если есть область видимости digital_pipeline. С функционалом digital pipeline могут работать публичные и приватные виджеты (подробнее Digital pipeline)
dp/settings Аналогичен блоку settings, но будет выводится при настройке виджета в digital воронке.
dp/action_multiple Обязательное поле в блоке dp, значения – true/false, определяет, может ли действие виджета растягиваться на несколько этапов
dp/webhook_url При указании webhook_url , amoCRM будет отправлять вебхук напрямую по указанному адресу. Url должен содержать протокол SSL
dp/title Название вашего триггера, которое отображается в настройках Digital Pipeline. Принимает ключ ланга из i18n.
widget/support/link Ссылка на поддержку интеграции (обязательно)
widget/support/email Email технической поддержки (обязательно в случае отсутствия ссылки на поддержку интеграции)
advanced/title Ключ в ланг файле для названия страницы виджета в настройках.
salesbot_designer Параметры для добавления виджета в конструкторе Salesbot. Подробней читайте по ссылке.
sms/endpoint Адрес, на который будет отправлен запрос для отправки системного SMS. Подробней читайте по ссылке.
mobile/frame_url Адрес, который будет открыт в специальной области в мобильном приложении. Подробней читайте по ссылке.
mobile/color HEX код цвета, который будет использован как подложка под заголовкам блока с виджетом.
amoforms_settings/title Ключ в ланг файле для отображения названия пункта виджета в веб-формах.
amoforms_settings/required Обязательность в веб-формах, прежде чем клиент нажмет обычную кнопку "Отправить", ему необходимо нажать на кнопку виджета.Необязательный параметр
amoforms_settings/error_text Ключ в ланг файле для отображения ошибки виджета в веб-формах.Необязательный параметр

Пример manifest.json

{
  "widget": {
    "name": "widget.name",
    "description": "widget.description",
    "short_description": "widget.short_description",
    "version": "1.0.0",
    "interface_version": 2,
    "init_once": false,
    "locale": ["ru", "en"],
    "installation": true,
    "support": {
      "link": "https://www.amocrm.com",
      "email": "support@amocrm.com"
    }
  },
  "locations": ["ccard-1", "clist-1", "digital_pipeline", "settings"],
  "tour": {
    "is_tour": true,
    "tour_images": {
      "ru": [
        "/images/tour_1_ru.png",
        "/images/tour_2_ru.png",
        "/images/tour_3_ru.png"
      ],
      "en": [
        "/images/tour_1_en.png",
        "/images/tour_2_en.png",
        "/images/tour_3_en.png"
      ],
      "es": [
        "/images/tour_1_es.png",
        "/images/tour_2_es.png",
        "/images/tour_3_es.png"
      ]
    },
    "tour_description": "widget.tour_description"
  },
  "settings": {
    "login": {
      "name": "settings.login",
      //указывает на файл локализации, в папке i18n
      "type": "text",
      //тип: текстовое поле
      "required": false
    },
    "password": {
      "name": "settings.password",
      //указывает на файл локализации, в папке i18n
      "type": "pass",
      //тип: пароль
      "required": false
    }
  },
  "dp": {
    "settings": {
      "message": {
        "name": "settings.message",
        "type": "text",
        "required": true
      }
    },
    "action_multiple": false
  },
  "advanced": {
    "title": "advanced.title"
  },
  "salesbot_designer": {
    "handler_code": {
      "name": "salesbot.handler_name",
      "settings": {
        "button_title": {
          "name": "salesbot.button_title",
          "type": "text",
          "default_value": "salesbot.button_title_default_value",
          "manual": true
        },
        "button_caption": {
          "name": "salesbot.button_caption",
          "type": "text",
          "default_value": "salesbot.button_caption_default_value",
          "manual": true
        },
        "text": {
          "name": "salesbot.text",
          "type": "text"
        },
        "number": {
          "name": "salesbot.number",
          "type": "numeric"
        },
        "url": {
          "name": "salesbot.url",
          "type": "url"
        }
      }
    }
  },
  "amoforms_settings": {
    "title": "amoforms_settings.title",
    "required": false,
    "error_text": "amoforms_settings.error_text"
  }
}

Особенности, связанные с oAuth интеграциями:

  1. В данный момент, логотип интеграции и логотип виджета это два разных файла. Логотип интеграции отображается в списке и на странице получения доступов, если у интеграции нет виджета. Если виджет есть, то он отображается только на странице получения доступов.
  2. Если виджет загружен в разделе amoМаркет => Мое приложение, то в его модальном окне будет отображаться название и описание, указанные в настройках интеграции, а не те, что указаны в manifest.json.

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

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

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

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

Пример i18n/ru.json

{
  "widget": {
    "name": "Demo виджет",
    "short_description": "Виджет для отсылки контакта во внутреннюю систему",
    "description": "Виджет, который служит для отправки данных из карточки контакта вашего домена #SUBDOMAIN# во внутренню систему"
  },
  "settings": {
    "login": "Логин",
    "password": "Пароль"
  },
  "userLang": {
    "firstWidgetText": "Кликните на кнопку, чтобы переслать данные на сторонний сервер:",
    "textIntoTheButton": "Отправить данные",
    "responseMessage": "Ответ сервера :",
    "responseError": "Ошибка"
  }
}

Пример i18n/en.json

{
  "widget": {
    "name": "Demo widget",
    "short_description": "Widget for sending the contact to the internal system",
    "description": "Widget that is used to send data from the contact card on your domain # SUBDOMAIN # in the internal system"
  },
  "settings": {
    "login": "Login",
    "password": "Password"
  },
  "userLang": {
    "firstWidgetText": "Please, click on the button, if you want:",
    "textIntoTheButton": "Send Data",
    "responseMessage": "Server response:",
    "responseError": "Failed"
  }
}

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

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

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

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

Типы полей