Если у вас еще нет amoCRM
Создать прямо сейчасЕсли вы разрабатываете интеграцию, которая может пригодится любому пользователю 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.
При добавлении дополнительной страницы расширенных настроек виджета в разделе “Настройки”, название страницы не должно повторять названия стандартных страниц, а также не вводить в заблуждение пользователя.
Нельзя:
Оплата счёта
Страница должна находится после всех наших стандартных страниц раздела “Настройки”.
Размещение интеграции может быть как моноязычным, так и мультиязычным.
В случае, когда вы заинтересованы размещаться не только в RU маркетплейс amoCRM, или только в US/ES/PT маркетплейс, существует ряд требований, для успешного прохождения модерации.
Изображения интеграции (логотип, тур) для английского, испанского и португальского языка содержащие текст должны быть на соответствующем языке.
Все прочие изображения, видео и инструкции, также, должны быть на английском, испанском или португальском языке.
Номер телефона поддержки должен начинаться с +1, допускается использования других номеров, но только с англоговорящей поддержкой.
Все ссылки должны вести на сайты на английском языке, либо испанском или португальском языках, при этом в содержимом сайтов не должно быть русских следов, будут проверены:
– Изображения
– Контактная информация
– Адреса
– Оферта и лицензии
– Цены
– Прочий контент сайта
Все цены должны быть в долларах или евро, при этом используемая платёжная система должна работать на территории Америки и Европейского Союза, например – PayPal
В описании интеграции не должен упоминаться домен .ru, в том числе почта поддержки.
Для того, чтобы модерация прошла как можно быстрее, перед отправкой на модерацию следует убедиться:
– все заполненные поля и изображения соответствуют требованиям данного раздела
– код вашей интеграции соответствует нашим требованиям
– интеграция протестирована и полностью работает в вашем техническом аккаунте
– если для работы интеграции требуются авторизационные данные к вашему сервису, необходимо их отправить в комментарии "Что нового (для модератора)"
– если интеграция доступна на нескольких языках, сверьтесь с разделом о переводах
После того как вы будете готовы к загрузке виджета, не забудьте удалить неиспользуемые файлы, картинки, скрипты и прочие файлы не используемые в работе интеграции. В архиве их быть не должно.
Содержание минимизированных и/или обфусцированных файлов усложняет модерацию, избегайте подобных вещей при создании архива виджета. Все текстовые файлы (.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
Обязательны для заполнения следующие поля:
– widget
– name
– description
– short_description
– locale
– installation
– locations
– tour
– is_tour должно быть значение “true”
– settings
Не нужно указывать области видимости в манифесте (в параметре “locations”), которые вы не используете в интеграции.
Файлы локализаций должны содержать текст на соответствующем языке. То есть в файле 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;
Подключение файлов со стилями
Файлы со стилями должны подключаться строго в соответствии с документацией.
Чем более читаемый и понятный код вы отправите на модерацию, тем быстрее пройдет процесс модерации, так она производится вручную специалистами отдела интеграции.
Разрешены только поясняющие комментарии в виджете.
Можно
// получим id аккаунта.
Нельзя
// var a = AMOCRM.constant(‘account’).id
В коде интеграции не должно быть:
тестовых данных
– дебагов
– alert и confirm
– и прочих следов разработки, которые не нужны для работы интеграции
Использование eval не допускается в связи с тем, что мы не можем доверять источнику кода, который он исполняет.
Допустимо использование console.debug для логирования важных для работы виджета сведений, чтобы с их помощью, впоследствии, можно было воспроизвести внештатную ситуацию.
При возникновении внештатной ситуации возможно использовать console.trace, но только внутри следующих блоков:
– Внутри блока catch
– В аргументе onRejected Promise
Все прочие методы объекта console, а также другие случаи использования console.trace могут привести к засорению console
Все переменные в виджете должны быть объявлены перед использованием, синтаксис должен быть корректным.
Список допустимых обращений описан в статье “Переменные окружения”.
Мы не гарантируем работу недокументированных переменных окружения в будущем, поэтому настоятельно рекомендуем отказаться от их использования.
Виджет не должен влиять на данные в глобальной переменной 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 запрещено, если в запрашиваемом файле содержится хотя бы один глобальный селектор.
Если необходимо использовать какую-то библиотеку, например, jquery.datepicker, эту библиотеку можно подключить через CDN.
При этом, для нас важно, в целях безопасности, чтобы это был доверенный CDN, на который вы никак не влияете.
Продолжая пример с jquery.datepicker, вы можете легко найти для него CDN, где будет указана ссылка на репозиторий проекта.
Таким образом мы поймём, что это не ваша реализация datepicker, а библиотека стороннего разработчика.
Единственное ограничение к таким подключаем библиотекам: у них должны быть не менее тысячи скачиваний в месяц.
Вы можете использовать iFrame в вашем коде, но с ним связаны следующее ограничение: нельзя исполнять код, полученный из iFrame.
Код виджета не должен опираться на стили switcher’a (switcher__on, switcher__off) – они подлежат удалению из системы.
