Оглавление

• Отображение шаблона виджета в правой колонке виджетов
• Добавление нового источника
• Добавление новой вкладки в карточке сделки, контакта, компании и покупателя
• Кастомный поиск при заполнении поля типа “Юр. лицо”
• Click 2 Call
• Написать первым

На данный момент система предусматривает 4 места в карточках (сделки, контакта, компании, покупателя), в которые может встроиться виджет:

1. Отображение шаблона виджета в правой колонке виджетов.
2. Добавление нового источника в контроле отправки в нижней части фида карточки.
3. Добавление новой вкладки в карточке сделки, контакта, компании и покупателя.
4. Возможность добавления своего обработчика на действие “Позвонить” в контекстное меню номера телефона у контакта в карточке сделки. Возможность добавления пункта “Написать первым” в контекстное меню номера телефона у контакта в карточке сделки.

Для работы виджета в карточке необходимо обязательно указать все локейшны карточек, в которых виджет должен работать:

• lcard (сделка)
• ccard (контакт)
• comcard (компания)
• cucard (покупатель)

Отображение шаблона виджета в правой колонке виджетов

Если ваш виджет использует правую колонку, то для того, чтобы система правильно посчитала количество виджетов в правой колонке до рендера карточки нужно указать постфикс 1 у локейшна. Например, если виджет работает в карточке сделки и выводится в правой колонке, то в manifest.json locations должен выглядеть, примерно, так:

{
  ...,
  "locations": [
    "lcard-1"
  ],
  ...
}

Для отрисовки собственного блока в правой колонке используйте вызов метода render_template() в колбэке render виджета. Пример вызова с необходимыми параметрами:

self.render_template({
  body: '',
  caption: {
    class_name: 'widget-caption-unique-class-name'
  },
  render: '<div class="widget-body-unique-class-name">' +
    ‘Количество сделок: {{count}}’ +
  '</div>'
}, { count: 10 });

Шапку с логотипом система отрисует самостоятельно, с теми изображениями, которые лежат у вас в папке images виджета, можно задать ей собственный caption.class_name, чтобы поправить что-то стилями.

За тело блока отвечают свойства body и render, в body можно передать готовую html-строку для отрисовки, в свойство render можно передать разметку, которая будет отрендерена с параметрами, переданными вторым аргументом в render_template.

Добавление нового источника

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

Для этого необходимо вызвать метод this.add_source(source_type, callback [,source_text]) объекта Widget

Всегда лучше стараться выбирать конкретный тип и, только если ни один не подходит, использовать “custom“. В этом случае внешние источники будут работать наравне с системными.

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

В этом случае callback всегда должен возвращать объект Promise.

// Пример реализации
self.add_source('sms', function (params) {
  /*
    params - объект с необходимыми параметрами для отправки смс, который передается в callback
    {
      'phone': 75555555555, // Телефон получателя
      'message': 'sms text', // Сообщение для отправки
      'contact_id': 12345 // Идентификатор контакта, к которому привязан номер телефона
    }
  */
  return new Promise(function (resolve, reject) {
    // Место, где описывается логика для отправки смс

    $.ajax({
      url: '/widgets/' + self.system().subdomain + '/loader/' + self.get_settings().widget_code + '/send_sms',
      method: 'POST',
      data: params,
      success: function () {
        // При успешном завершении будет автоматически создано примечание типа 'sms'
        resolve();
      },
      error: function () {
        reject();
      }
    });
  });
});

Если тип источника иной, то в callback передается JQuery элемент контрола, который можно использовать для создания любой логики.

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

self.add_source('email', function ($el) {
  console.log($el);
}, 'Gmail');

Добавление новой вкладки в карточке сделки, контакта, компании и покупателя

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

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

Для добавления новой вкладки необходимо:

1. В файле manifest.json указать в объекте locations следующие области (необходимые карточки, для примера мы приводим все возможные): “lcard-0″, “ccard-0”, “comcard-0”, “settings”, “card_sdk”;
2. Реализовать методы объекта callbacks, описанные ниже, для рендеринга товаров в карточке сущности.
3. Создать новую интеграцию или обновить существующий архив интеграции в разделе амоМаркет;
4. Включить виджет.

Методы необходимые для подключения источников данных.

В файле script.js виджета обязательно должны быть созданы 4 метода в объекте callbacks:

1. loadPreloadedData
2. loadElements
3. linkCard
4. searchDataInCard

Описание методов

Метод loadPreloadedData()

Метод вызывается при инициализации вкладки, связанной с виджетом.

Отвечает за отображение предлагаемых к добавлению в карточку данных при открытии поля поиска.

Метод должен возвращать объект типа Promise, который, по выполнении вашего запроса вернет массив [Obj1, Obj2, … ObjN], где Obj — объект, описывающий элемент в формате:

{
  "id": 934244, // ID
  "sku": "SNI/01/136/0500", // SKU код
  "name": "Name", // Наименование
  "price": "999" // Цена
}

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

loadPreloadedData: function () {
  return new Promise(_.bind(function (resolve, reject) {
    self.crm_post(
      'http://my.sdk.api.com/sdk_back/',
      {},
      function (msg) {
        resolve(msg);
      },
      'json'
    );
  }), this);
}

Если ваш виджет не работает с товарами, а нужно просто отрендерить какие-то данные во вкладку, то можно использовать как раз этот метод со следующим содержимым:

loadPreloadedData: function () {
  var $widget_tab = $('#' + self.get_settings().widget_code);

  $widget_tab.html('widget body here');

  return Promise.resolve({});
}

Метод loadElements(type, id)

Метод вызывается при инициализации вкладки, связанной с виджетом.

Отвечает за отображение привязанных к карточке элементов.

Метод должен возвращать объект типа Promise, который, по выполнении вашего запроса вернет массив [Obj1, Obj2, … ObjN], где Obj — объект, описывающий элемент в формате:

{
  "id": 934244, // ID
  "sku": "SNI/01/136/0500", // SKU код
  "name": "Name", // Наименование
  "price": "999", // Цена
  "quantity": 2 // Количество
}

Параметры:

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

loadElements: function (type, id) {
  return new Promise(_.bind(function (resolve, reject) {
    self.crm_post(
      'http://my.sdk.api.com/sdk_back/?products=true&type='+type.type+'&entity_id='+id,
      {},
      function (msg) {
        resolve(msg);
      },
      'json'
    );
  }), this);
}

Метод linkCard(links)

Метод вызывается при сохранении привязанных элементов в карточки, при изменении колличества и их отвязке.

Отвечает за привязку/отвязку элементов в карточку.

Параметры метода:

Пример реализации метода:

linkCard: function (links) {
  return new Promise(_.bind(function (resolve, reject) {
    self.crm_post(
      'http://my.sdk.api.com/sdk_back/link.php',
      links,
      function () {},
      'json'
    );

    resolve();
  }), this);
}

Метод searchDataInCard(query, type, id)

Метод вызывается при поиске элементов.

Отвечает за отображение найденных элементов к карточке элементов.

Метод должен возвращать объект типа Promise, который, после выполнения вашего запроса, вернет массив [Obj1, Obj2, … ObjN], где Obj — объект, описывающий элемент в формате:

{
  "id": 934244, // ID
  "sku": "SNI/01/136/0500", // SKU код
  "name": "Name", // Наименование
  "price": "999" // Цена
}

Параметры метода

Пример реализации метода:

searchDataInCard: function (query, type, id) {
  return new Promise(_.bind(function (resolve, reject) {
    self.crm_post(
      'http://my.sdk.api.com/sdk_back/search.php',
      {
        query: query,
        type: type,
        id: id
      },
      function (msg) {
        resolve(msg);
      },
      'json'
   );
  }), this);
}

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

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

Для реализации данной функции можно использовать предусмотренный метод. Для этого необходимо поместить в массив 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();
}];

Click 2 Call

При работе пользователя в amoCRM, можно обеспечить вызов какой-либо функции, при нажатии на номер телефона или e-mail адрес контакта.

Данная возможность реализуется готовой функцией add_action(). Возможные параметры

Рассмотрим пример использования функции add_action(), поместив её в функцию обратного вызова init, объекта callbacks структуры script.js.

Пример:

this.callbacks = {
  init: function () {
    self.add_action('phone', function (data) {
      self.crm_post(
        'http://127.0.0.1/file.php',
        { call_to: data.value  },
        function (msg) {
          console.log('Данные отправлены');
        },
        'text',
        function () {
          console.log('Error');
        }
      );
    });
  }
};

Важно помнить, что необходимо объявить область подключения виджета в manifest.json. Для выполнения функции add_action(), нужно задать области видимости, где есть отображённые номера телефонов или email адреса. Либо задать ограниченный спектр областей срабатывания, на ваше усмотрение, подробнее об областях подключения читайте здесь. В примере заданы все области, где встречаются номера телефонов и email адреса.

Пример:

{
  ...
  "locations": [
    "ccard-1",
    "clist-1",
    "lcard-1",
    "llist-1",
    "cucard-1",
    "culist-1 ",
    "comcard-1"
  ],
  ...
}

Для того, чтобы изменить надпись на кнопке, вызываемой во время нажатия на номер телефона или email адрес, необходимо в директории i18n структуры вашего виджета, внести соответствующие изменения в файле локализации *.json, так, как указано в примере ниже. Если параметр “call_action” не задан, по умолчанию в надпись на кнопке будет подставлено имя вашего виджета, являющееся обязательным параметром в manifest.json. Значение “call_action” будет подставлено в кнопку автоматически, при инициализации виджета.

Пример (файл ru.json):

{
  "widget": {
    "call_action": "Позвонить"
  }
}

Написать первым

Интерфейс amoCRM позволяет инициировать переписку с клиентом из карточки. Для этого достаточно создать карточку и добавить в нее контакт с номером телефона. 

Если ваш канал поддерживает функцию “написать первым”, то он отобразится в выпадающем списке Click 2 Call (подробнее Регистрация нового канала).