Card SDK

Functions and principles of interaction with the SDK card.

What is an SDK?

SDK card allows developers of widgets to connect their own data source to the card (lead, contact, company, buyer). At the moment, developers can display products in the card. Bind and untie them, search for them, change their number.

What do I need to use the SDK?

  • In the manifest.json file, you need to specify the following areas in the locations object: "lcard-0", "ccard-0", "comcard-0", "settings", "card_sdk";

  • Create a new widget or update an existing one through Settings -> API;

  • Enable widget.

How to connect an SDK to a card

  • After the widget is turned on, it will be displayed in the interface, in the control window of the attached tabs of the card (the ellipsis next to the tabs on the left side of the card)(available only from the Account Administrator)

  • After the widget is connected to the card, and also selected, it will be initialized.

What is necessary for correct work in the card

In the script.js file of the widget, you must create 4 methods in the callbacks object

  • loadPreloadedData

  • loadElements

  • linkCard

  • searchDataInCard

Description of methods and examples

The loadPreloadedData () method

The method is called when the tab associated with the widget is initialized.

Responsible for displaying the proposed to add to the card data when opening the search field.

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

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

An example of a method implementation:

  1. loadPreloadedData: function () {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             // Let's make a request to a remote server
  4.             self.crm_post(
  5.                 'http://my.sdk.api.com',
  6.                 {},
  7.                 function (msg) {
  8.                     // Let's bring the elements to the desired format and resolve
  9.                     resolve(msg);
  10.                 },
  11.                 'json'
  12.             );
  13.         }), this);
  14.     }
The loadElements (type, id) method

The method is called when the tab associated with the widget is initialized.

It is responsible for displaying the elements attached to the card.

The method must return an Promise-type object that, upon execution of your query, will return an array [Obj1, Obj2, ... ObjN], where Obj is an object describing the element in the format:

  1. {
  2.     id: {number},
  3.     sku: {string},
  4.     name: {string},
  5.     price: {string},
  6.     quantity: {number}
  7. }
Parameters of the method:
Parameter Description
type {Object} The information about the entity from which the request is made, contains the following properties:
  • id: {Number} - ID of the entity (1 - contact, 2 - lead, 3 - company, 12 - buyer)
  • type: {String} - the text identifier of the entity
id {Number} The ID of the element from which the query is made
Example of method implementation
  1. loadElements: function (type, id) {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             // Let's make a request to a remote server
  4.             self.crm_post(
  5.                 'http://my.sdk.api.com',
  6.                 {},
  7.                 function (msg) {
  8.                     // Let's bring the elements to the desired format and resolve
  9.                     resolve(msg);
  10.                 },
  11.                 'json'
  12.             );
  13.         }), this);
  14.     }

The linkcard method (links)

The method is called when the attached items are stored in the cards, with the change in the number and their unbinding.

It is responsible for linking / unlinking elements to the card.

Parameters of the method :

Parameter Description
links {Object}
links/link An array of objects with properties:
  • from: {String} - the entity to which to bind
  • from_id: {Number} - the id of the entity to which the binding is made
  • quantity: {Number} - number
  • to_id: {Number} - product id
  • to_widget_id: {String} - widget code
links/unlink An array of objects with properties:
  • from: {String} - the entity to which to bind
  • from_id: {Number} - the id of the entity to which the binding is made
  • quantity: {Number} - number
  • to_id: {Number} - product id
  • to_widget_id: {String} - widget code
An example of a method implementation:
  1. linkCard: function (links) {
  2.         return new Promise(_.bind(function (resolve, reject) {
  3.             // Let's make a request to a remote server
  4.             self.crm_post(
  5.                 'http://my.sdk.api.com/sdk_back/link.php',
  6.                 links,
  7.                 function () {
  8.                 // We do not process errors that could occur on your side, in this block you can execute
  9. Your code
  10.                 },
  11.                 'json'
  12.             );
  13.  
  14.  
  15.             resolve();
  16.         }), this);
  17.     }
The searchDataInCard method (query, type, id)

The method is called when searching for items.

It is responsible for displaying the found elements to the elements card.

The method must return an Promise-type object that, after executing your query, returns an array [Obj1, Obj2, ... ObjN], where Obj is an object describing the element in the format:

  1. {
  2.     id: {number},
  3.     sku: {string},
  4.     name: {string},
  5.     price: {string}
  6. }
Method parameters
Parameter Description
query {String} search query string
type {Number} the type of the entity from which the request is made (1 - contact, 2 -lead, 3 - company, 12 - buyer)
id {Number} The ID of the element from which the request is made.
Example of method implementation:
  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.     }

Description of the PHP application for working with the SDK

Installation on the server

To install the test application, you need to download the downloaded archive to your server.

Then you need to change the data to connect to the database in the header.php file, then go to the script page with the GET parameter transfer: install.php? Install = y.

At this point, two tables and test data are created in the database specified in the previous step.

Scripts index.php, link.php and search.php will be called by amoCRM through the script.js widget.

Description of the database tables:
Table Description
products
  • id - product ID
  • sku - article number
  • name - the name of the product
  • price - price of goods
links
  • entity - the type of the entity to which the binding was made
  • entity_id - the id of the element to which the binding was made
  • quantity - number, which is transmitted when binding and changing the quantity
  • product_id - product id, unique key
Creating a new product

To create new products, you can refer to the script by passing the necessary GET parameters, create.php? New_product = true & sku = {article} & name = {product name} & price = {price}

index.php

The script index.php returns a list of products, in the example widget, this script is prompted when loading the typed types to the card and opening the search.

When you open the card, you will be prompted for this script with the parameters passed:? Products = true & type = {entity type} & entity_id = {id of the entity}.

When you open the search, it's just a request for this script, it returns all the elements.

search.php

The search.php script accepts the query parameter, which searches the database and returns the found items.

link.php

The script link.php is responsible for binding and unbinding of data to the card. Gets the link or unlink array, depending on the action (bind / unlink).

Parameter Description
from entity to which to link
from_id id of the element to be bound to
quantity quantity
to_id Item ID