Structure of widget
After you extract the archive, you will see in the root files, PHP libraries and the widget_example folder, whose structure we will cover:
| File | Description | |||||
|---|---|---|---|---|---|---|
| manifest.json require |
A json file containing a description of the widget, widget settings, widget options displayed to the user, localizations with which the widget works. | |||||
| script.js | A JS file that will be connected on the user’s side in the areas specified in the manifest.json | |||||
| widget.php | An optional file that contains the business logic in PHP, if necessary. Hosting php scripts on the Kommo side is only available for public widgets that are available to all Kommo users | |||||
| images/ | The folder for placing the image files that are used in the widget should contain 5 png files that will be used as the logo of the widget in different areas of visibility. The size of each file should not exceed 300 KB. logo_min.png and logo_medium.png – required, if the widget works in cards, it is used in all lists and cards of contacts or deals in a minimized and unfolded state respectively. Images logo_main and logo_small duplicate the goals of logo_min, respectively, are required to be shipped from November 2018. It’s also necessary to download logo.png to support older versions.
|
|||||
| i18n/ | A folder that contains localization files in the format key: value. localizations: English (en), Spanish (es) and Portuguese (pt). All translations will be available in both JS and PHP part |
As you can see, only manifest.json file is required
Getting Started
As an example, we’ll take a widget that is based only on JS. It displays a button in the contact card, when you click on which data from the
card is sent to the external system, where for example the php-script is treated with a stub that can be written in any language.
This is a common task, because It is not uncommon for the business process to transfer data from Kommo, according to the actions of the employee, to the internal system of the company. Or, on the contrary, output additional data from the external system to Kommo cards.
In addition, the Kommo API supports an event model of calling third-party scripts via the WebHooks mechanism. It allows for certain events, for example, changing the status of a transaction or changing a contact, accessing the URL script specified in the settings and transferring the actual data to it.
Also, public widgets can interact with the functionality of digital pipeline deals and buyers. For more information, see the Digital pipeline
So, first, copy the folder with the widget sample and call it widget. This is the basis of our future widget.
We will not use the file widget.php, so you can safely remove it. Next, we begin to deal with all the files in turn.
manifest.json
Begin to edit the file, guided by the table of descriptions of its parameters. You can use a link to language messages in the value, if needed.
Attention! Since November, 2018 three OBLIGATORY fields have been added to manifest.json. The first two fields are responsible for the feedback and are located in the “Feedback” button (you must specify a link to the support site or email). Please note email is a less priority way to contact. A brief description of the widget will be located on the left side of the modal window.
| Settings | Description |
|---|---|
| widget | The block contains all the basic settings of the widget |
| widget/name | The name of the widget, including the widget list. The example is widget.name, which means that the value will be taken from the corresponding i18n folder file, depending on the localization. |
| widget/description | A full description of the widget is shown in the widget settings window. You can use html-tags, as well as special short-tags in order to form the most personalized description. For example, you need to show a description by telling the user the subdomain of the Kommo account in which it is running. List of tags:
# HOST # – the current host; |
| widget/short_description | A brief text describing the functionality of the widget |
| widget/version | Widget version. It only carries an informative load. |
| widget/interface_version | (int) The interface version (1,2) for which system interface the widget is loaded. By default, you must leave 2. Interface 1 – the previous version of the interface of the entire Kommo system, without the use of AJAX. Registration for the old version is now closed. |
| widget/init_once | (true / false) specifies whether to collect the js object widget 1 time per session with the Kommo interface. When the widget is initialized, the functions render (), init () and bind_actions () are called (more about them in the part script.js). Specifying true or false controls the ability to call the init () and bind_actions () functions each time when changing from an area to an area (for more information about connection areas), or to call them only once. For example, telephony widgets constantly hold the WebSocket connection and its breakage should not occur, so init_once should be set to true. If there is no context common for all pages, it’s better to put it in false. |
| widget/locale | An array of localizations on which the widget is available. To publish a widget in English, support must be provided in English by the developer. |
| widget/installation | (true / false) If false, the widget will only appear in the widget list, without prompting for a setting or setting in the account. This is true when all the settings occur in another system that interacts with Kommo via the API. |
| locations | The interfaces in which the widget should be displayed. An array that must be filled in if you want to use the js part of the widget. More about the areas. Possible locations: llist – list of leads, clist – contact list, tlist – task list, lcard – lead card, ccard – contact card, card_sdk – SDK card, culist – customer list, cucard – customer card, digital_pipeline – digital funnel of transactions and buyers, catalogs – SDK lists, advanced_settings – the widget’s advanced settings page. It is also necessary to inform our system whether the widget will use the right column for display, you can do this by adding 0 or 1 after specifying the zone. That is, if you specify “clist-0”, the widget is initialized in this zone, but will not use the right column. For example, the panel for the WEB-background is not in the right column of the widgets, but in the bottom in any interface. Therefore, for all connection points in the widget settings should be written 0, but on each page it is initialized |
| settings | An array of widget settings available to the user, i.e. Fields that will be present in the widget’s settings window and populated by the user. This section is required only if installation = true, if installation = false, then this section is not needed, because in the settings window only the widget’s description will be displayed. The key in the array is the FIELD_CODE field code |
| settings/FIELD_CODE/name | Field name (only the link to the element in the lang file) |
| settings/FIELD_CODE/type | Type of field. Available options:
Details of the field types are explained in the section Types of fields in the section |
| settings/FIELD_CODE/required | true / false mandatory field filling by the user |
| dp | Block widgets configuration in the digital pipeline. This block must be included in manifest.json only if there is a scope of digital_pipeline. With the digital pipeline functionality, only public widgets that have a file widget.php can work, in which there is an endpoint digital_pipeline (more details Digital pipeline) |
| dp/settings/ | Similar to the settings block, but it will be displayed when adjusting the widget in the digital funnel. |
| dp/settings/action_multiple | Required field in the dp block, values – true / false, determines whether the widget action can be stretched into several stages |
| widget/support/link | Link to support integration (required) |
| widget/support/email | Technical support email (required if there is no link for integration support) |
Example manifest.json
{
"widget": {
"name": "widget.name",
"description": "widget.description",
"short_description": "widget.short_description",
"version": "1.0.1",
"interface_version": 2,
"init_once": true,
"locale": [
"en",
"es"
],
"installation": true,
"support": {
"link": "https://www.kommo.com",
"email": "support@kommo.com"
}
},
"locations": [
"ccard-1",
"clist-0",
"lcard-1",
"llist-0",
"settings",
"digital_pipeline",
"advanced_settings",
"salesbot_designer"
],
"tour": {
"is_tour": true,
"tour_images": {
"en": [
"/images/tour_1_en.png",
"/images/tour_2_en.png",
"/images/tour_3_en.png"
],
"es": [
"/images/tour_1_es.png",
"/images/tour_2_es.png",
"/images/tour_3_es.png"
]
},
"tour_description": "widget.tour_description"
},
"settings": {
"login": {
"name": "settings.login",
"type": "text",
"required": true
},
"api_key": {
"name": "settings.api_key",
"type": "text",
"required": true
},
"account": {
"name": "settings.account",
"type": "text",
"required": true
}
},
"dp": {
"settings": {
"message": {
"name": "dp.message",
"type": "text",
"required": true
}
},
"action_multiple": false,
"webhook_url": "https://example.com/webhook"
},
"advanced": {
"title": "advanced.title"
},
"salesbot_designer": {
"handler_code": {
"name": "salesbot.handler_name",
"settings": {
"button_title": {
"name": "salesbot.button_title",
"type": "text",
"default_value": "salesbot.button_title_default_value",
"manual": true
},
"button_caption": {
"name": "salesbot.button_caption",
"type": "text",
"default_value": "salesbot.button_caption_default_value",
"manual": true
},
"text": {
"name": "salesbot.text",
"type": "text"
},
"number": {
"name": "salesbot.number",
"type": "numeric"
},
"url": {
"name": "salesbot.url",
"type": "url"
}
}
}
}
}i18n Localization files
The manifest.json example uses constructs of the form widget.name. They are needed if your widget should work in more than one language.
In this case, you need to create three localization files for the English, Spanish and Portuguese languages, pt.json, es.json and en.json, in the i18n folder. Then, depending on the language of the account, both in the JS part and in PHP, language messages will be available in the appropriate language.
IMPORTANT: If 2 localizations are used, it is necessary that the files are the same in structure.
Example i18n/en.json
{
"widget": {
"name": "Demo widget",
"short_description": "Widget for sending the contact to the internal system",
"description": "Widget that is used to send data from the contact card on your domain # SUBDOMAIN # in the
internal system"
},
"settings": {
"login": "Login",
"password": "Password"
},
"userLang": {
"firstWidgetText": "Please, click on the button, if you want:",
"textIntoTheButton": "Send Data",
"responseMessage" : "Server response:",
"responseError" : "Failed"
}
}Example i18n/en.json
{
"widget": {
"name": "Demo widget",
"short_description": "Widget for sending the contact to the internal system",
"description": "Widget that is used to send data from the contact card on your domain # SUBDOMAIN # in the
internal system"
},
"settings": {
"login": "Login",
"password": "Password"
},
"userLang": {
"firstWidgetText": "Please, click on the button, if you want to sent data:",
"textIntoTheButton": "Send Data",
"responseMessage" : "Server response:",
"responseError" : "Failed"
}
}To access language messages from the widget’s JS code, use the self.i18n (‘obj_name’) method, where obj_name is one of the objects in the localization file.
Examples of manifest.json files are in the Type of fields of the settings section manifest.json
Common Mistakes
- Many files, in particular, manifest.json have the format json, it is better to make sure the syntax is correct before using them, using the online checking of json files. One of the most common errors is loading a file with an incorrect syntax
- Encoding – all files must be encoded in UTF-8 without BOM
- Even before the first load of the widget in the manifest, it is necessary to replace the code and key from the above example with the unique
- Often in a packed archive, the widget folder is at the root, as the first level, but in fact should already be immediately lying files
- If the wrong manifest was originally loaded, then you need to generate a new code and a key, because the previous one will be pre-credited