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 карточки