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

В папке 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). Тур — это набор картинок, на которых демонстрируется функционал виджета. Обязательными поля данного свойства являются: поле с указанием включением тура для виджета, ключи локализаций для картинок тура и ключ ланга, содержащего краткий текст, который будет выведен в момент показа тура виджета. Подробнее можно узнать в статье.

Пример 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, то необходимо сгенерировать новый код и ключ, т.к. предыдущий будет дескредитирован

Типы полей