In this help you will learn basic principles of the application development for Bitrix24 and the procedure you will have to complete to register your application in Bitrix24 Marketplace. For developers, whose applications may require third party access to private resources, we shall discuss operation principles of the OAuth authentication server, and take a look at some examples.
Bitrix24 App Design Guidelines
For your service to be convenient to your users, 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 that are 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 to be an entry point for such application, and install.html shall be deemed to be an installer, if available (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. Such apps will never be available or visible to the Intranet users directly. The external applications are used to receive data for the use by mobile, Windows or any other software. Remember to check the Available as script only option when registering the application in Bitrix24 Marketplace. This will enable the application to get a OAuth 2.0 key. (Download example);
Types can be combined in one application. 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.
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 to IFRAME, a special authentication code is passed on the URL (using the OAuth authentication server).
- to resize the IFRAME window: BX24.resizeWindow, BX24.setTitle, BX24.getScrollSize;
- to call native interfaces: BX24.selectUser, BX24.selectUsers, BX24.selectAccess.
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:
- Social network groups (workgroups, projects);
- Data storage (information blocks);
- Company Structure (Departments);
- Activity Stream;
When registering your application in Bitrix24 Marketplace, you will have to select the data items your applications will access and use – that is, assign user data access permissions.
When you start developing your application, one of the first steps to take is register and deploy it on your Bitrix24 testing installation. It is only then that you can try to run your app on a real Bitrix24 service.