Интерфейс карточки

На данный момент система предусматривает 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

Параметр Тип Описание

source_type

string

Тип источника. Может быть “sms”, “chat” , “email” и “custom”. В зависимости от типа виджет будет автоматически выбираться при загрузке карточки, если последнее событие в фиде сообщение чата или sms, или email.

callback

function

Функция-обработчик источника. Ниже есть примеры реализации.

source_text

string

Название источника, которое будет видеть пользователь. Имеется для всех типов, кроме “sms”, и является обязательным параметром. Если виджет мультиязычный, то должно подставляться из языковых сообщений.

Всегда лучше стараться выбирать конкретный тип и, только если ни один не подходит, использовать “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: {number},
  sku: {string},
  name: {string},
  price: {string}
}

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

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_code.html('widget body here');

  return Promise.resolve({});
}

Метод loadElements(type, id)

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

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

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

{
  id: {number},
  sku: {string},
  name: {string},
  price: {string},
  quantity: {number}
}

Параметры:

Параметр Описание

type

{Object} Информация о сущности, из которой делается запрос, содержит в себе свойства:

  • id: {Number} – ID сущности (1 – контакт, 2 – сделка, 3 – компания, 12 – покупатель)
  • type: {String} – текстовый идентификатор сущности

id

{Number} ID элемента, из которого делается запрос.

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

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)

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

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

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

Параметр Описание

links

{Object}

links/link

Массив объектов со свойствами:

  • from: {String} – сущность, к которой осуществляется привязка
  • from_id: {Number} – id сущности, к которой осуществляется привязка
  • quantity: {Number} – количество
  • to_id: {Number} – id товара
  • to_widget_id: {String} – код виджета

links/unlink

Массив объектов со свойствами:

  • from: {String} – сущность, к которой осуществляется привязка
  • from_id: {Number} – id сущности, к которой осуществляется привязка
  • quantity: {Number} – количество
  • to_id: {Number} – id товара
  • to_widget_id: {String} – код виджета

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

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: {number},
  sku: {string},
  name: {string},
  price: {string}
}

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

Параметр Описание

query

{String} строка запроса на поиск

type

{Number} тип сущности, из которой делается запрос (1 – контакт, 2 – сделка, 3 – компания, 12 – покупатель)

id

{Number} ID элемента, из которого делается запрос.

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

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);
}

Click 2 Call

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

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

Параметр Описание

type

Тип передаваемого параметра, может быть: “email”, “phone”

action

Функция, которая будет вызываться при нажатии на номер телефона или email адрес

Рассмотрим пример использования функции 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 (подробнее Регистрация нового канала).