SDK карточки

В данном разделе описывается функции и принципы взаимодействия с SDK карточки.

Что такое SDK?

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

Что необходимо для использования SDK?

  • В файле manifest.json необходимо указать в объекте locations следующие области:”lcard-0", "ccard-0", "comcard-0", "settings", "card_sdk";
  • Создать новый виджет или обновить существующий через раздел Настройки -> API;
  • Включить виджет.

Как подключить SDK в карточку

  • После включения виджета он начнет отображаться в интерфейсе, в окне управления привязанными вкладками карточки (троеточие рядом с вкладками в левой части карточки) (доступно только у Администратора аккаунта);
  • После того как виджет будет подключен в карточку, а также выбран, он будет инициализирован.

Что необходимо для корректной работы в карточке

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

  • loadPreloadedData
  • loadElements
  • linkCard
  • searchDataInCard

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

Метод loadPreloadedData()

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

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

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

  1. {
  2.     id: {number},
  3.     sku: {string},
  4.     name: {string},
  5.     price: {string}
  6. }

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

  1.     loadPreloadedData: function () {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             //Сделаем запрос на удаленный сервер
  4.             self.crm_post(
  5.                 'http://my.sdk.api.com',
  6.                 {},
  7.                 function (msg) {
  8.                     //Приведем элементы к нужному формату и зарезолвим
  9.                     resolve(msg);
  10.                 },
  11.                 'json'
  12.             );
  13.         }), this);
  14.     },

Метод loadElements(type, id)

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

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

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

  1. {
  2.     id: {number},
  3.     sku: {string},
  4.     name: {string},
  5.     price: {string},
  6.     quantity: {number}
  7. }

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

PARAMETER DESCRIPTION
type {Object} Информация о сущности из которой делается запрос, содержит в себе свойства:
  • id: {Number} - ID сущности (1 - контакт, 2 - сделка, 3 - компания, 12 - покупатель)
  • type: {String} - текстовый идентификатор сущности
id {Number} ID элемента, из которого делается запрос.

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

  1.     loadPreloadedData: function () {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             //Сделаем запрос на удаленный сервер
  4.             self.crm_post(
  5.                 'http://my.sdk.api.com',
  6.                 {},
  7.                 function (msg) {
  8.                     //Приведем элементы к нужному формату и зарезолвим
  9.                     resolve(msg);
  10.                 },
  11.                 'json'
  12.             );
  13.         }), this);
  14.     },

Метод linkCard(links)

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

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

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

PARAMETER DESCRIPTION
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} - код виджета

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

  1.     linkCard: function (links) {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             //Сделаем запрос на удаленный сервер
  4.             self.crm_post(
  5.                 'http://my.sdk.api.com/sdk_back/link.php',
  6.                 links,
  7.                 function () {
  8.                 //Мы не обрабатываем ошибки, которые могли произойти на вашей стороне, в данном блоке Вы можете выполнить Ваш код
  9.                 },
  10.                 'json'
  11.             );
  12.  
  13.  
  14.             resolve();
  15.         }), this);
  16.     }
  17.    

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

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

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

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

  1. {
  2.     id: {number},
  3.     sku: {string},
  4.     name: {string},
  5.     price: {string}
  6. }

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

PARAMETER DESCRIPTION
query {String} строка запроса на поиск
type {Number} тип сущности, из которой делается запрос (1 - контакт, 2 - сделка, 3 - компания, 12 - покупатель)
id {Number} ID элемента, из которого делается запрос.

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

  1.     searchDataInCard: function (query, type, id) {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             self.crm_post(
  4.                 'http://my.sdk.api.com/sdk_back/search.php',
  5.                 {
  6.                     query: query,
  7.                     type: type,
  8.                     id: id
  9.                 },
  10.                 function (msg) {
  11.                     resolve(msg);
  12.                 },
  13.                 'json'
  14.             );
  15.         }), this);
  16.     }

Пример виджета (JS-часть), который взаимодействует с PHP приложением, описаным ниже

Скачать


Описание PHP приложения, для работы с SDK

Установка на сервер

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

Затем необходимо изменить данные для подключения к БД в файле header.php, затем зайти на страницу скрипта с передачей GET параметра: install.php?install=y.

В этот момент в БД, указанной в предыдущем шаге создаются 2 таблицы и тестовые данные.

Скрипты index.php, link.php и search.php будут вызываться со стороны amoCRM через script.js виджета.

Описание таблиц базы данных

Таблица Описание
products
  • id - идентификатор товара
  • sku - артикул товара
  • name - название товара
  • price - цена товара
links
  • entity - тип сущности, к которой выполнена привязка
  • entity_id - id элемента, к которому выполнена привязка
  • quantity - кол-во, которое передается при привязке и изменении колличества
  • product_id - id товара, уникальный ключ

Создание нового товара

Создать новые товары можно обращаясь к скрипту, передавая необходимые GET-параметры, create.php?new_product=true&sku={артикул}&name={название товара}&price={цена}

index.php

Скрипт index.php возвращает список товаров, в виджете-примере к этому скрипту происходит запрос при загрузке привязанных типов к карточке и открытии поиска.

При открытии карточки произойдет запрос на данный скрипт с передачей параметров: ?products=true&type={тип сущности}&entity_id={id сущности}.

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

search.php

Скрипт search.php принимает параметр query, по которому происходит поиск в БД и возвращает найденные элементы.

link.php

Скрипт link.php отвечает за привязку и отвязку данных к карточке. Получает массив link или unlink в зависимости от действия (привязка/отвязка).

PARAMETER DESCRIPTION
from сущность, к которой осуществляется привязка
from_id id элемента, к которой осуществляется привязка
quantity количество
to_id ID товара

Пример PHP-приложения, для работы с SDK

Скачать