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

Оглавление

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

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

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

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

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

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

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

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

Оформление и описание интеграции

Чем проще работа с интеграцией, тем больше пользователей ее будет использовать. Поэтому необходимо соблюдать следующие правила в оформлении интеграции:

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

Нельзя
amoForms

Можно
Форма обратной связи

Упоминание “amoCRM” в описании интеграции допускается только при условии его корректного написания. Например, нельзя “AMO CRM” или “amocrm” и т.п.

Вы можете использовать html разметку в описании интеграции, при этом необходимо соблюдать следующие правила:

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

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

Перед отправкой интеграции на модерацию необходимо протестировать ее работу в вашем техническом аккаунте. В случае выявления ошибок в ходе тестирования их необходимо исправить и только после этого отправлять интеграцию на модерацию.

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

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

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

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

Интеграция не должна в каком-либо виде содержать в себе упоминание/рекламу приватных интеграций или маркетплейса приватных интеграций.

Оплата

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

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

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

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

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

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

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

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

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

Размещение интеграции может быть как моноязычным, так и мультиязычным.

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

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

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

Номер телефона поддержки должен начинаться с +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 и pt.json файлах должны вести на сайты на английском, испанском или португальском языках соответственно.

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

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

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

Изображения и логотипы

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

Размеры изображений:

  • для тура – 1188 на 616px
  • иконка интеграции – 400 на 272px
  • логотип – 108 на 108px

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

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

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

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

При использовании технологии Drag&Drop, drop area не должны располагаться в:

  • левом меню
  • прямоугольнике, расположенном в верхней части пользовательского интерфейса, шириной в область видимости, высотой в 65px
  • областях с системными управляющими элементами (кнопки настроек, сохранения, импорта, и других…)

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

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

Виртуальные клики на кнопку “Установить” и “Отключить” – запрещены.

Стили

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

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

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

В виджете не должно быть подключения внешних файлов-зависимостей через document.createElement(‘script’) и вставку этого элемента напрямую в head.

Все внешние зависимости должны подключаться через requirejs в блоке зависимостей в define.

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

Список внешних ресурсов, которые желательно использовать при подключении библиотек, т.к. туда нельзя загружать собственные библиотеки:

Список внешних ресурсов, которые допустимо использовать при подключении библиотек, но каждую библиотеку мы будем проверять:

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

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

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

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

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

Единственное ограничение к таким подключаем библиотекам: у них должны быть не менее тысячи скачиваний в месяц.

iframe

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

Deprecated

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