Требования к публичным интеграциям

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

Технический аккаунт

Для взаимодействия с нашими интеграторами, которые желают опубликоваться в нашем маркетплейс мы создали удобный и быстрый способ взаимодействия с отделом интеграций – технический аккаунт. Для того чтобы мы могли сделать ваш аккаунт техническим, нужен новый аккаунт, который вы можете самостоятельно зарегистрировать на amoCRM.ru. После этого, нужно активировать чат с технической поддержкой, и написать следующее “Нужен чат с отделом интеграций, для создания технического аккаунта”.
Такой аккаунт предназначен для разработки и тестирования виджета (НЕ для ведения своего бизнеса). В этот аккаунт добавляется технический пользователь amoCRM, для того, чтобы при возникновении ошибок в интеграции, разработчик отдела интеграции мог зайти в этот аккаунт и воспроизвести ошибку самостоятельно. Тем кто еще не опубликовался, аккаунт выдается на 1 месяц, после публикации он будет продлеваться на постоянной основе автоматически.

Авторизация

Для авторизации в amoCRM используется механизм авторизации oAuth 2.0, более безопасный и лишенный многих минусов по сравнению с механизмом API ключей.

Общие требования

Для того чтобы интеграция была понятна клиенту, вы должны соблюдать рекомендации которые мы опишем ниже.

Простота в использовании

Технически неподготовленный пользователь должен понимать:

– как включить интеграцию
– как её настроить
– как с ней работать
– где получить поддержку

Чем работа с интеграцией понятнее, тем больше пользователей ее будет использовать.

Качество изготовления

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

Безопасность

Интеграция не должна собирать информацию, которая не требуется для функционирования интеграции.

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

Оплата

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

Обращаем ваше внимание: упоминание оплаты лицензий amoCRM через партнеров не допускается, вне зависимости от метода упоминания.

Соглашение о неконкуренции

Разработчик интеграции не должен вести разработку систем, схожих с amoCRM.

Расширенные настройки

При добавлении дополнительной страницы расширенных настроек виджета в разделе “Настройки”, название страницы не должно повторять названия стандартных страниц, а также не вводить в заблуждение пользователя.

Нельзя:
Оплата счёта

Страница должна находится после всех наших стандартных страниц раздела “Настройки”.

Публикация en и es интеграций

Размещение интеграции может быть как моноязычным, так и мультиязычным.
В случае, когда вы заинтересованы размещаться не только в RU маркетплейс amoCRM, или только в US/ES маркетплейс, существует ряд требований, для успешного прохождения модерации.

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

Номер телефона поддержки должен начинаться с +1, допускается использования других номеров, но только с англоговорящей поддержкой.

Все ссылки должны вести на сайты на английском языке, либо испанском языках, при этом в содержимом сайтов не должно быть русских следов, будут проверены:
– Изображения
– Контактная информация
– Адреса
– Оферта и лицензии
– Цены
– Прочий контент сайта

Все цены должны быть в долларах или евро, при этом используемая платёжная система должна работать на территории Америки и Европейского Союза, например – PayPal

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

Требования к архиву widget.zip

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

Содержание минимизированных и/или обфусцированных файлов усложняет модерацию, избегайте подобных вещей при создании архива виджета. Все текстовые файлы (.js, .css, .json, .md, etc…) должны быть в кодировка UTF-8 без BOM, а также использовать перевод строки Unix (\n).

Список обязательных файлов, которые должен содержать архив widget.zip:
– manifest.json
– i18n/*.json
– images/
  – logo.png
  – logo_main.png
  – logo_medium.png
  – logo_min.png
  – logo_small.png

Файл manifest.json

Обязательны для заполнения следующие поля:
– widget
  – name
  – description
  – short_description
  – locale
  – installation
– locations
– settings

Не нужно указывать области видимости в манифесте (в параметре “locations”), которые вы не используете в интеграции.

Файлы i18n

Файлы локализаций должны содержать текст на соответствующем языке. То есть в файле i18n/en.json не должно быть текстов на русском языке, а также упоминания .ru доменов.

Все ссылки в en.json и es.json файлах должны вести на сайты на английском, либо испанском языках соответственно.

Требование к клиентской части интеграции

Клиентская часть интеграции (виджет) не должна перекрывать элементы управления amoCRM, не должна мешать пользователю взаимодействовать с интерфейсом amoCRM.

Изменение интерфейса

Интеграция не должна изменять интерфейсы, которые не включены в разрешенный список.

Запрещено изменение левого меню, кроме случаев, описанных в документации.

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

При использовании технологии Drag&Drop, drop area не должны располагаться в:
– левом меню
– прямоугольнике, расположенном в верхней части пользовательского интерфейса, шириной в область видимости, а высотой в 65px
– областях с системными управляющими элементами (кнопки настроек, сохранения, импорта, etc…)

Запрещается скрывать/изменять/подменять рейтинги и отзывы в разделе интеграции и модальном окне настроек виджетов.

При сохранении настроек интеграции кнопка “Сохранить” должна находится внизу модального окна.

Запрещены виртуальные клики на кнопку “Установить”.

Стили

Запрещены манипуляции с глобальными селекторами CSS.

Нельзя
input { background: red; }

Виджет не должен в css файлах иметь общие классы с нашей системой. Все стили должны быть указаны относительно корневого селектора виджета. Это даёт возможность внутри виджета переопределять какие угодно стили, не затрагивая системные.

Можно
#amo_widget_code
.control-select { color: green }
Нельзя
.control-select { color: red }

Комментарии

Разрешены только поясняющие комментарии в виджете.

Можно
// наш фирменный цвет
Нельзя
// background: #fafafa;

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

JavaScript

Чем более читаемый и понятный код вы отправите на модерацию, тем быстрее пройдет процесс модерации, так она производится вручную специалистами отдела интеграции.

Комментарии

Разрешены только поясняющие комментарии в виджете.

Можно
// получим id аккаунта.
Нельзя
// var a = AMOCRM.constant(‘account’).id

Следы разработки

В коде интеграции не должно быть:
тестовых данных
– дебагов
alert и confirm
– и прочих следов разработки, которые не нужны для работы интеграции

Логирование

Допустимо использование console.debug для логирования важных для работы виджета сведений, чтобы с их помощью, впоследствии, можно было воспроизвести внештатную ситуацию.

При возникновении внештатной ситуации возможно использовать console.trace, но только внутри следующих блоков:
– Внутри блока catch
– В аргументе onRejected Promise

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

Несуществующие переменные

Все переменные в виджете должны быть объявлены перед использованием, синтаксис должен быть корректным.

Использование глобальной переменной AMOCRM

Список допустимых обращений описан в статье “Переменные окружения”.

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

Виджет не должен влиять на данные в глобальной переменной AMOCRM, он может только читать данные оттуда.

Работа с сетью

Запрещены синхронные запросы (async: false), так как их использование замедляет загрузку остальных скриптов, что в конечном счете сказывается на скорости загрузки страниц сервиса.

В циклах нельзя отправлять запросы к amoCRM, а также использовать методы crm_post и $authorizedAjax, т.к. это создаёт излишнюю нагрузку на amoCRM.

Внешние зависимости

В виджете не должно быть подключения внешних файлов-зависимостей через document.createElement(‘script’) и вставку этого элемента напрямую в head.
Все внешние зависимости должны подключаться через requirejs в блоке зависимостей в define.
Дополнительные плагины или иные внешние подключения в виджет не должны грузиться с внешних ресурсов за исключением публичных библиотек.
Список внешних ресурсов, которые желательно использовать при подключении библиотек, т.к. туда нельзя загружать собственные библиотеки:
jQuery CDN
https://yandex.ru/dev/jslibs/
https://developers.google.com/speed/libraries/
https://docs.microsoft.com/en-us/aspnet/ajax/cdn/overview

Список внешних ресурсов, которые допустимо использовать при подключении библиотек, но каждую библиотку мы будем проверять:
https://pagecdn.com/
https://www.jsdelivr.com/
https://cdnjs.com/

Подключение стилей из cdn

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

Подгрузка дополнительных файлов из CDN

Если необходимо использовать какую-то библиотеку, например, jquery.datepicker, эту библиотеку можно подключить через CDN.
При этом, для нас важно, в целях безопасности, чтобы это был доверенный CDN, на который вы никак не влияете.
Продолжая пример с jquery.datepicker, вы можете легко найти для него CDN, где будет указана ссылка на репозиторий проекта.
Таким образом мы поймём, что это не ваша реализация datepicker, а библиотека стороннего разработчика.
Единственное ограничение к таким подключаем библиотекам: у них должны быть не менее тысячи скачиваний в месяц.

iFRAME

Вы можете использовать iFrame в вашем коде, но с ним связаны следующее ограничение: нельзя исполнять код, полученный из iFrame.

Deprecated

Код виджета не должен опираться на стили switcher’a (switcher__on, switcher__off) – они подлежат удалению из системы.