In this help you will learn the basic principles of the development of applications for Bitrix24 and the procedure you will have to undertake to register you application in Marketplace. For developers whose applications may require third party access to private resources, we shall discuss the principles of operation of the OAuth authentication server, and take a look at some examples.
Bitrix24 App design guidelines
For the convenience of the users of your service, we recommend that you create the app using a standardized formulation. Recommendations for formation can be downloaded here.
Notes on Bitrix24 App Development
All Bitrix24 applications may fit in the following three major categories.
- Applications hosted in the Bitrix cloud. These apps are usually uploaded as a single archive file containing all the necessary resources: HTML, styles, scripts and images. The file index.html is deemed an entry point for such application, and install.html, if available, shall be deemed an installer. (Download example);
If an application is located on a third party’s server, the host name of the application must contain a point. For the purposes of development and testing, the application can be located in the local network, but, for example, localhost will not serve for this; direct IP should be specified instead. (Local address will open in iframе on the application page at the portal. Browser limit: communication between the portal and frame contents is implemented via postMessage. It was noted that some browser versions process messages incorrectly if these messages come from localhost.)
When developing and testing an application, there is no need to have a server signed with an SSL certificate. Self-signed certificate will suffice, provided that it is added to the browser exceptions.
- External applications: these use the API but have no user interface or menu items. It will never be available or visible to the Intranet users directly. The external applications are used to receive data for use by mobile, Windows or any other programs. Remember to check the Available as script only option when registering the application in Marketplace. This will enable the application to get a OAuth 2.0 key. (Download example);
Types can be combined in one application. An application can work from a third party server, use frames, and at the same time work from the “outside” using OAuth authorization to obtain access to Rest API.
An application can be structured as required by design, however:
- an entry point must exist. For an application of the first kind, an entry point is index.html. The entry point page will be opened in a frame on a Bitrix24 web page;
- an installer may be included in the package. The installer page (install.html for an application of the first kind) will be opened by a user with administrative permission to install the application, in a frame on a Bitrix24 web page.
For security reasons, an application is embedded in the Intranet pages using IFRAME. IFRAME loads the URL specified when registering the application. If the application was uploaded as an archive, the URL is obtained from the Bitrix website.
To save a user the trouble of logging in again in IFRAME, a special authentication code is passed on the URL (using the OAuth authentication server).
To use REST or other features in a client side script, include the JS Library. Applications of the second kind can use REST at server side, because the authentication key will be passed on to the entry point (or installer) as the POST parameters AUTH_ID and AUTH_EXPIRES.
The library needs to be included before it can be used.
The REST methods are available for the following data items:
When registering your application in Marketplace, you will have to select the data items your applications will access and use – that is, assign user data access permissions.
The date and time fields are read and written in ISO 8601
When you start developing your application, one of the first steps to take is register and install it on your testing installation of Bitrix24. It is only then that you can try to run your app on a real Bitrix24 service.