SDK карточки

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

Что такое SDK?

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

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

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

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

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

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

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

  • loadPreloadedData
  • loadElements
  • linkCard
  • 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',
                {},
                function (msg) {
                    //Приведем элементы к нужному формату и зарезолвим
                    resolve(msg);
                },
                'json'
            );
        }), this);
    }

Метод 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',
                {},
                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);
    }

Пример виджета (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 в зависимости от действия (привязка/ отвязка).

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

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

Скачать