JS SDK

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

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

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

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

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

self.add_call_notify = function (mess) {
    var w_name = self.i18n('widget').name,
        date_now = Math.ceil(Date.now() / 1000),
        lang = self.i18n('settings'),
        n_data = {
            from: mess.from,
            to: mess.to,
            duration: mess.duration,
            link: mess.link,
            text: w_name + ': ' + mess.text,
            date: date_now
        };

    if (mess.element && mess.element.id && mess.element.type) {
        n_data.element = mess.element;
    }

    AMOCRM.notifications.add_call(n_data);
};

/*---------------------------------------*/
var notify_data = {};
notify_data.from = '+7 (999) 111 22 33';
notify_data.to = 'User Name';
notify_data.duration = 65;
notify_data.link = 'https://example.com/dialog.mp3';
notify_data.text = 'Widget text';
notify_data.element = {id: 1003619, type: "contact"};

self.add_call_notify(notify_data);

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

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

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

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

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

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

AMOCRM.widgets.legal_handlers = [function (data) {
    var def = $.Deferred();

    $.ajax({
        type: 'POST',
        url: 'http://www.example.com/',
        dataType: 'json',
        data: data
    }).done(_.bind(function (response) {
        var res;

        res = _.map(response._embedded.items, function (item) {
            return {
                name: item.name,
                inn: item.inn,
                kpp: item.kpp,
                ogrn: item.ogrn,
                type: item.type,
                address: item.address
            };
        });

        this.def.resolve(res);
    }, {def: def}))
        .fail(_.bind(def.reject, def, []));

    return def.promise();
}];

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

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

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

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

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

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

errors.add_error(n_data, callbacks);

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

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

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

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

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

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

define(['jquery', 'lib/components/base/modal'], function ($, Modal) {
    var CustomWidget = function () {
        this.callbacks = {
            // ...
            bind_actions: function () {
                // ...
                var data = '<h1>Test</h1><p>Some text</p>';
                modal = new Modal({
                    class_name: 'modal-window',
                    init: function ($modal_body) {
                        var $this = $(this);
                        $modal_body
                            .trigger('modal:loaded') // запускает отображение модального окна
                            .html(data)
                            .trigger('modal:centrify')  // настраивает модальное окно
                            .append('');
                    },
                    destroy: function () {
                    }
                });
                // ...
                return true;
            }
        }
    }
    return CustomWidget;
});

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

 

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

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

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

AMOCRM.sdk.showUserStatus ( ) // объект со всеми id пользователей и их статусами
//Пример ответа:
{
    {
        id: 123456 ,
        online: true
    },
    {
        id: 123456 ,
        online: false
    }, ...
}

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

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

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

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

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

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

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

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

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

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

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

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

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

AMOCRM.sdk.setCallingStatus(boolean)

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

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

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

if (AMOCRM.sdk.getCallingStatus()) {
    // code
} else {
    // code
}

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