Structure

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 amoCRM side is only available for public widgets that are available to all amoCRM 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.

logo_main.png
400px x 272px

logo_small.png
108px x 108px

logo_medium.png
240px x 84px

logo_min.png
84px x 84px

logo.png
130px x 100px
i18n/ A folder that contains localization files in the format key: value. Currently, only two localizations are possible: Russian (ru) and English (en). 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 amoCRM, 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 amoCRM cards.

In addition, the amoCRM 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 amoCRM account in which it is running. List of tags:
# HOST # - the current host;
# SUBDOMAIN # - account subdomain;
# LOGIN # - login of the current user, authorized user;
# API_HASH # - hash key of the user;
# ACCOUNT_ID # - id of the current account in the system;
# LINK # http://example.test/link_to_copy#/LINK# - the tag of this view is converted to a field and a button, when clicked on, the link is copied;
# USER_ID # - id of the current user on the system.
widget/short_description A brief text describing the functionality of the widget
widget/code What you need to enter with Latin characters when generating a key on the developer page. Your widget code
widget/secret_key The secret widget key that you generated on the developer page
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 amoCRM 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 amocrm 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 amoCRM 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:
  • text
  • pass
  • users (a list of users of the system with 1 text field per each is required if you need to enter some information for each employee, for example, an internal phone number for IP telephony)
  • users_lp (list of users of the system with 2 fields (login, password) for each.

Details of the field types are explained in the section Types of fields in the section settings manifest.json.
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

  1. {
  2. "widget":{
  3.   "name": "widget.name",
  4.   "description": "widget.description",
  5.   "short_description": "widget.short_description",
  6.   "code": "new_widget",
  7.   "secret_key": "57009cb5048a72191f25b01355c17d10dc349df20d4fe2ad0c69930223e13955",
  8.   "version": "1.0.0",
  9.   "interface_version" : 2,
  10.   "init_once" : false,
  11.   "locale": [
  12.         "ru",
  13.         "en"
  14.         ],
  15.     "installation": true,
  16.    "support": {
  17.         "link": "https://www.amocrm.com" ,
  18.         "email": "support@amocrm.com"
  19.     }
  20.     },
  21. "locations": [
  22.     "ccard-1",
  23.     "clist-1",
  24.     "digital_pipeline",
  25.     "settings"
  26.     ],
  27. "settings": {
  28.     "login":{
  29.         "name": "settings.login", //indicates the localization file in the i18n folder
  30.         "type": "text", //type: text field
  31.         "required": false
  32.         },
  33.     "password": {
  34.         "name": "settings.password",//indicates the localization file in the i18n folder
  35.         "type": "pass", //type:password
  36.         "required": false
  37.         }
  38.   },
  39.   "dp": {
  40.     "settings": {
  41.         "message": {
  42.             "name": "settings.message",
  43.             "type": "text",
  44.             "required": true
  45.         }
  46.     },
  47.     "action_multiple": false
  48.   }
  49. }

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 two localization files for the Russian and English languages, ru.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

  1. {
  2.     "widget": {
  3.         "name": "Demo widget",
  4.         "short_description": "Widget for sending the contact to the internal system",
  5.         "description": "Widget that is used to send data from the contact card on your domain # SUBDOMAIN # in the
  6. internal system"
  7.     },
  8.     "settings": {
  9.         "login": "Login",
  10.         "password": "Password"
  11.     },
  12.    "userLang": {
  13.         "firstWidgetText": "Please, click on the button, if you want:",
  14.         "textIntoTheButton": "Send Data",
  15.     "responseMessage" : "Server response:",
  16.     "responseError" : "Failed"
  17.     }
  18. }

Example i18n/ru.json

  1. {
  2.     "widget": {
  3.         "name": "Demo widget",
  4.         "short_description": "Widget for sending the contact to the internal system",
  5.         "description": "Widget that is used to send data from the contact card on your domain # SUBDOMAIN # in the
  6. internal system"
  7.     },
  8.     "settings": {
  9.         "login": "Login",
  10.         "password": "Password"
  11.   },
  12.  
  13.     "userLang": {
  14.         "firstWidgetText": "Please, click on the button, if you want to sent data:",
  15.         "textIntoTheButton": "Send Data",
  16.     "responseMessage" : "Server response:",
  17.     "responseError" : "Failed"
  18.     }
  19. }

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