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

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

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

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

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

Авторизация

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

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

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

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

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

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

Оформление описаний

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

Для этого необходимо соблюдать следующие правила в оформлении интеграции:
– Описание интеграции до установки должно донести пользователю для чего интеграция нужна, а также как она способствует улучшению работы с amoCRM
– Описание интеграции после установки обязательно должно включать следующие пункты:
  – информация о том как настраивать интеграцию, либо где можно ознакомиться с инструкцией по настройке
  – информация о том, как использовать интеграцию после подключения в amoCRM

Вы можете использовать html разметку в описании интеграции, при этом необходимо соблюдать следующие правила:
– Все ссылки должны быть оформлены в виде html тега a, например <a href="https://amocrm.ru" target="_blank" referrerpolicy="no-referrer">amoCRM</a>
– Не стоит злоупотреблять оформлением текста, т.к. это приводит к ухудшению удобочитаемости

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

Нельзя
amoForms

Можно
Формы для amoCRM

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

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

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

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

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

Оплата

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

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

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

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

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

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

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

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

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

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

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

Номер телефона поддержки должен начинаться с +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
– tour
  – is_tour должно быть значение “true”
– settings

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

Файлы i18n

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

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

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

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

Пользователь должен иметь возможность в любой момент отключить интеграцию.

Изображения, логотипы, а также иконки интеграции не должны быть анимированными.

Размеры изображений:
– для тура – 1188 на 616px
– иконка интеграции – 400 на 272px
– логотип – 108 на 108px

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

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

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

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

При использовании технологии 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
– и прочих следов разработки, которые не нужны для работы интеграции

Использование eval

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

Логирование

Допустимо использование 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/
https://unpkg.com/

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

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

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

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

iFRAME

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

Deprecated

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