JS SDK

JS методы и объекты для работы с amoCRM

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

Всплывающее уведомление

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

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

  1. self.add_call_notify = function (mess) {
  2.     var w_name = self.i18n ( 'widget' ).name ,
  3.         date_now = Math.ceil ( Date.now ( ) / 1000 ) ,
  4.         lang = self.i18n ( 'settings' ) ,
  5.         n_data = {
  6.             from: mess.from ,
  7.             to: mess.to ,
  8.             duration: mess.duration ,
  9.             link: mess.link ,
  10.             text: w_name + ': ' + mess.text ,
  11.             date: date_now
  12.         } ;
  13.  
  14.     if (mess.element && mess.element.id && mess.element.type ) {
  15.         n_data.element = mess.element ;
  16.     }
  17.    
  18.     AMOCRM.notifications.add_call (n_data) ;
  19. } ;
  20.  
  21. /*---------------------------------------*/
  22. var notify_data= { } ;
  23. notify_data.from = '+7 (999) 111 22 33' ;
  24. notify_data.to = 'User Name' ;
  25. notify_data.duration = 65 ;
  26. notify_data.link = 'https://example.com/dialog.mp3' ;
  27. notify_data.text = 'Widget text' ;
  28. notify_data.element = { id: 1003619 , type: "contact" } ;
  29.  
  30. self.add_call_notify (notify_data) ;

Пример не только вызывает окошко уведомления, но и навешивает ссылку.

Кастомный поиск при заполнении поля типа "Юр. лицо"

В системе реализована возможность использовать кастомный поиск юридических лиц при заполнении поля типа Юр. лицо

Для реализации данной функции можно использовать предусмотренный метод. Для этого необходимо поместить в массив AMOCRM.widgets.legal_handlers функцию, которая будет возвращать ajax. Ajax должен вернуть массив объектов следующей структуры:

  1. {
  2.     name: 'ООО ШОКОЛАДНИЦА' ,
  3.     inn: '5009051111' ,
  4.     kpp: '500901001' ,
  5.     ogrn: '1065009000187' ,
  6.     type: '1' ,
  7.     address: 'МОСКОВСКАЯ ОБЛ.,Г ДОМОДЕДОВО,КАШИРСКОЕ ШОССЕ, Д 70' ,
  8. }

Пример реализации:

  1. AMOCRM.widgets.legal_handlers = [ function (data) {
  2.     var def = $.Deferred ( ) ;
  3.  
  4.     $.ajax ( {
  5.         type: 'POST' ,
  6.         url: 'http://www.example.com/' ,
  7.         dataType: 'json' ,
  8.         data: data
  9.     } ).done (_.bind ( function (response) {
  10.         var res;
  11.        
  12.        res = _.map (response._embedded.items , function (item) {
  13.            return {
  14.                name: item.name ,
  15.                inn: item.inn ,
  16.                kpp: item.kpp ,
  17.                ogrn: item.ogrn ,
  18.                type: item.type ,
  19.                address: item.address
  20.            } ;
  21.        } ) ;
  22.  
  23.        this.def.resolve (res) ;
  24.     } , {def: def} ) )
  25.     .fail (_.bind (def.reject , def, [ ] ) ) ;;
  26.  
  27.     return def.promise ( ) ;
  28. } ] ;

Уведомление об ошибке

Рекомендуем использовать подобные уведомления, если JS на странице производит какие-то фоновые действия (вызываемые скрыто от пользователя, не по его вызову). В таких случаях вы можете уведомлять пользователя о том, что что-то пошло не так и какие действия ему необходимо предпринять.

К примеру, вы разрабатываете виджет телефонии и в фоне соединяетесь с сервером для ожидания событий о входящих звонках. В какой-то момент вы поняли, что не можете установить соединение с вашим сервером и ожидаемый функционал не сработает. Лучше уведомить об этом пользователя сообщением об ошибке (с описанием причин) с указанием телефона технической поддержки.

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

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

  1. var  errors = AMOCRM.notifications ,
  2.     date_now = Math.ceil ( Date.now ( ) / 1000 ) ,
  3.     header = self.get_settings ( ).widget_code ,
  4.     text = 'error'
  5.     var n_data = {
  6.                 header: header, //код виджета  
  7.                 text: '<p>' +text+ '</p>' , //текст уведомления об ошибке
  8.                 date: date_now //дата
  9.             } ,
  10.     callbacks = { done: function ( ) {console.log ( 'done' ) ; } , //успешно добавлено и сохранено AJAX done
  11.                   fail: function ( ) {console.log ( 'fail' ) ; } , //AJAX fail
  12.                   always: function ( ) {console.log ( 'always' ) ; } //вызывается всегда
  13.                 } ;
  14.  
  15.     errors.add_error (n_data,callbacks) ;

Рассмотрим параметры подробнее:

  • header- (string) имя виджета будет отображаться в заголовке
  • text - (string) сообщение об ошибке
  • date - дата
  • callbacks объект функций обратного вызова. При добавлении нового сообщения или ошибки AJAX запрос отправляется на сервер, который возвращает номер данного сообщения в случае успешного сохранения данных, в зависимости от успешности запроса срабатывает одна из переданных функций данного объекта

Объект Modal для работы с модальным окном.

Для работы с ним его необходимо подключить в файле script.js

В данном примере показано использование объекта модального окна Modal

Отдельный пример приведен ниже.

  1. define( [ 'jquery' , 'lib/components/base/modal' ] , function ($, Modal) {
  2. var CustomWidget = function ( ) {
  3.   this.callbacks = {
  4.     // . . .
  5.     bind_actions: function ( ) {
  6.     //.  .  .
  7.     var data = '<h1>Test</h1><p>Some text</p>' ;
  8.   modal = new Modal( {
  9.   class_name: 'modal-window' ,
  10.    init: function ($modal_body) {
  11.    var $this = $( this ) ;
  12.    $modal_body
  13.       .trigger ( 'modal:loaded' ) //запускает отображение модального окна
  14.       .html (data)
  15.       .trigger ( 'modal:centrify' )  //настраивает модальное окно
  16.       .append ( '<span class="modal-body__close"><span class="icon icon-modal-    close"></span></span>' ) ;
  17.      } ,
  18.          destroy: function ( ) {
  19.       }
  20.          } ) ;
  21.     //.  .  .
  22.                 return true ;
  23.            }
  24.     }
  25.         }
  26.   return CustomWidget;
  27. } ) ;

Для работы с объектом модальное окно необходимо подключить его через require (define в начале script.js) и передать параметры : class_name, init() , destroy(). В init передаются данные для отображения в модальном окне и события trigger для того, чтобы запустить методы объекта Modal и вывести модальное окно в DOM.

Метод для получения статуса online пользователей

Данный метод позволяет получать информацию об online статусах пользователей. Статус может быть true (если пользователь в сети) или false (если пользователя нет в сети).

Получение статуса online для всех пользователей

  1. AMOCRM.sdk.showUserStatus ( ) // объект со всеми id пользователей и их статусами
  2. //Пример ответа:
  3. {
  4.  {
  5.     id: 123456 ,
  6.    online: true
  7.   } ,
  8.   {
  9.     id: 123456 ,
  10.     online: false
  11.   } , ...
  12. }

Для получения всех пользователей и их online статусов метод вызвается без флага и возвращает в объекте id всех пользователей и их online статусы.

Получение id всех пользователей в сети

  1. AMOCRM.sdk.showUserStatus ( 'online' ) // массив всех id пользователей online
  2. //Пример ответа:
  3. [ 123456 , 123457...]

Для получения списка всех пользователей, которые находятся в сети, данный метод необходимо вызвать с флагом “online”. В этом случае он отдаст массив, содержащий id пользователей в сети.

Получение статуса online пользователя по его id

  1. var id_user = 123456 ; //Уникальный идентификатор аккаунта
  2. var status_user = AMOCRM.sdk.showUserStatus (id_user) ; // online статус пользователя (true или false)

Для получения статуса пользователя по его id необходимо вызвать метод c Уникальным идентификатором аккаунта. При этом данный метод вернет true (если пользователь в сети) или false (если пользователя нет в сети).

Обработка ошибок

  1. AMOCRM.notifications.show_user_status (‘someString’) // объект со всеми id пользователей и их статусами

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

Метод для установки статуса звонка

Данный метод позволяет установить статус звонка. Входящий параметр boolean (true/false).

Установка статуса звонка

  1. AMOCRM.sdk.setCallingStatus(boolean)

Метод для получения статуса звонка

Данный метод позволяет узнать статус телефонного разговора. Результат выполнения boolean.

Получение статуса звонка

  1. if (AMOCRM.sdk.getCallingStatus ( ) ) {
  2.   // code
  3. } else {
  4.   // code
  5. }

Данный функционал необходим для того, чтобы не произошел обрыв разговора через виджет телефонии в момент обновления (отгрузки изменений) amoCRM.

SDK карточки