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

Оглавление

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

1. Свод правил для Интеграторов

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

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

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

1.2. Рекомендация других разработок Интегратора

  • Рекомендация других Публичных интеграций допускается только в отдельном разделе Настройки интеграции.
  • Интеграция не должна предоставлять возможность установки или устанавливать “за собой” другие ваши виджеты.
  • Интеграция не должна в каком-либо виде содержать в себе упоминание/рекламу и тем более установку Приватных интеграций.

1.3. Сторонние сервисы

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

1.4. Отзывы пользователей

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

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

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

1.6. Поддержка пользователей

  • При сбое или во внештатных ситуациях, для оповещения пользователей должно выводиться сообщение с причиной возникновения ситуации и контактными данными Интегратора.
  • Обращаем ваше внимание на важность соблюдения должного уровня поддержки пользователей. Частые сообщения о проблемах с вашей интеграцией, отрицательные отзывы и запросы на возврат лицензий могут говорить о несоблюдении свода правил для Интеграторов.
    Запрещено:
    • Направлять клиентов в поддержку amoCRM – Интегратор должен обеспечить поддержку своих интеграций. При необходимости Интегратор может обратиться в поддержку amoCRM из технического аккаунта.
    • Вводить в заблуждение клиента – формировать у клиента ожидание, что его вопрос должны решить в поддержке amoCRM.
    • Запрашивать у клиента учетные данные (логин и пароль от amoCRM) для осуществления поддержки.
    • Представляться технической поддержкой amoCRM.

2. Формирование задачи

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

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

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

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

  • Клиентская часть интеграции (виджет) не должна перекрывать элементы управления amoCRM и мешать пользователю взаимодействовать с интерфейсом amoCRM.
  • Пользователь должен иметь возможность в любой момент отключить интеграцию.
  • Интеграция не должна изменять интерфейсы, которые не включены в разрешенный список.
  • Запрещено изменение левого меню, кроме случаев, описанных в документации.
  • Блок виджета нельзя размещать ниже блока центра нотификаций в левой части меню.
  • При использовании технологии Drag&Drop, drop area не должны располагаться в:
    • левом меню
    • прямоугольнике, расположенном в верхней части пользовательского интерфейса, шириной в область видимости, высотой в 65px
    • областях с системными управляющими элементами (кнопки настроек, сохранения, импорта, и других…)
  • При сохранении настроек интеграции кнопка “Сохранить” должна находиться внизу модального окна.
  • Если интеграция не требует настроек, то допускается виртуальный клик на кнопку “Сохранить”. Виртуальные клики на кнопку “Установить” и “Отключить” – запрещены.

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

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

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

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

  • Размещение интеграции может быть как моноязычным, так и мультиязычным.
  • Если вы заинтересованы в размещении не только в RU или только в US/ES/PT маркетплейсе amoCRM, то ознакомьтесь с требованиями для успешного прохождения модерации.
  • Если изображения интеграции (логотип, тур) для английского, испанского и португальского языков, содержат текст, он должен быть на соответствующем языке.
  • Все прочие изображения, видео и инструкции также должны быть на соответствующем языке.
  • Номер телефона поддержки должен начинаться с +1. Также допускается использование других номеров, при условии оказания поддержки на английском языке.
  • Все ссылки должны вести на сайты на соответствующих языках. Будут проверены:
    • Изображения
    • Контактная информация
    • Адреса
    • Оферта и лицензии
    • Цены
    • Прочий контент сайта
  • Все цены должны быть в долларах или евро. Используемая платежная система должна работать на территории Америки и Европейского Союза, например – PayPal.
  • В описании интеграции не должен упоминаться домен .ru, в том числе почта поддержки.

3. Разработка интеграции

3.1. Требования к архиву 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

3.1.1. JavaScript

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

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

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

  • В коде интеграции не должно быть следующих следов разработки:
    • тестовых данных
    • дебагов, за исключением случаев описанных ниже
    • alert и confirm
    • прочих следов разработки, которые не нужны для работы интеграции
  • Использование eval не допускается в связи с тем, что мы не можем доверять источнику кода, который он исполняет.
  • Допустимо использование console.debug для логирования важных для работы виджета сведений, чтобы с их помощью, можно было впоследствии воспроизвести внештатную ситуацию.
  • При возникновении внештатной ситуации возможно использовать console.trace, но только внутри следующих блоков:
    • Внутри блока catch
    • В аргументе onRejected Promise
  • Все прочие методы объекта console, а также другие случаи использования console.trace могут привести к засорению console
  • Все переменные в виджете должны быть объявлены перед использованием, синтаксис должен быть корректным.
  • Виджет не должен влиять на данные в глобальной переменной AMOCRM, он может только читать данные оттуда. Список допустимых обращений описан в статье "Переменные окружения". Мы не гарантируем работу недокументированных переменных окружения в будущем, поэтому настоятельно рекомендуем отказаться от их использования.
  • При работе с сетью запрещено:
    • использовать синхронные запросы (async: false), так как это замедляет загрузку остальных скриптов, что в конечном счете сказывается на скорости загрузки страниц сервиса.
    • в циклах отправлять запросы к API amoCRM.
    • в циклах использовать методы crm_post и $authorizedAjax.

3.1.2. Файл manifest.json
  • Обязательны для заполнения следующие поля:
    • widget
        – name
        – description
        – short_description
        – locale
        – installation
    • locations
    • settings
  • Не нужно указывать области видимости в манифесте (в параметре "locations"), которые вы не используете в интеграции.

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

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

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

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

Можно

amo_widget_code

.control-select { color: green }

Нельзя
.control-select { color: red }

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

Можно
// наш фирменный цвет

Нельзя
// background: #fafafa;

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

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

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

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

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

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

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

3.2.3. iframe

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

3.3. Deprecated

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

4. Публикация в маркетплейс

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

4.1. Название интеграции

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

4.2. Описание интеграции

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

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

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

4.4. Персональные данные

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

4.5. Оплата

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