Функции и принципы взаимодействия с 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}
}

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

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

 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)

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

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

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

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

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

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

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

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 виджета.

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

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

Для создания новых товаров можно обратиться к скрипту, передав необходимые 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 в зависимости от действия (привязка/ отвязка).

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

Скачать