Views: 6163
Last Modified: 17.08.2020

  Interactive applications

Information listed below is useful when you need to write code for your own client. If you don't need a new client, but only added interactivity feature into already existing application, find more information here.

RT-servers connection is used for creating a truly interactive application: instant application status changes and interface updates without AJAX requests.

  Application development

There are two ways to connect the service: Long polling and websocket. When user enters the site, user's browser, desktop or mobile application establishes and maintain constant connection with Push-server.
Usually this is done via WebSocket, employed by 95% modern browsers. When a browser does not support WebSocket technology, Long Polling is used.

It's recommended to use websocket as the main method for establishing RT-server connection. Long polling is used only for devices without websocket support or when client experiences problems when connecting to websocket.

To retrieve server and connectivity data, use REST command pull.application.config.get

For connecting to the server, get a required type (for example, websocket_secure) in server settings (server field) for required connection. Next, add Connection channels are listed in GET parameter CHANNEL_ID. all available channels (separated by /.) to this type of connection. Add the parameter clientId. When Bitrix24 account uses cloud-based push server, add the parameter clientId to URL to connect to server.

Websocket connection example for Bitrix24 Self-hosted push-server:

wss://rt.bitrix24.com/sub/?CHANNEL_ID=46a437d2336d4a88e4e9b3cd956ecf45:6221e0eb48981fce67cf4756e82e8102.7910bb25e660bf211fdec15e33c5e25e4c3b644a/fb9f7e13dc3d595c5aefe1a0216c27a2.2887eebc6ae160713a732893462dce9d8e23a7b0

Websocket connection example for Bitrix24 Cloud push-server:

wss://rtc-cloud-ms1.bitrix.info/subws/?CHANNEL_ID=beb502091dfc9b93d7fd648aa4ec332e%3A7cc478c89de71ec78bf4820d3d814a3e.4f5466742ca1e59e263fee732a7dbe002889ba91%2F1ab4f7a440cea35a1abccd5c2566c688.b33914ef342e5cd21e4fbcf4ac92acd2e9ea3755&clientId=fcda45d0859442735f07b8bb5825ded1

Each channel operation time is limited by 12 hours. You must track the expiration time and execute repeated request pull.application.config.get when one of channels operation time has expired.

To access channel history, add special get-tags to the address specified above: &tag= and &time= (for server version 2 and lower) or &mid= (for version 3 and higher). You can get all the required data for get-tags when reviewing each command from channel. After connecting with these tags, you'll have a one-time access to messages that weren't available for the current session.

  General format for commands from server

Server version 3 and lower, when queried, receives text as follows:

#!NGINXNMS!#{"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}}#!NGINXNME!#
#!NGINXNMS!#{"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}#!NGINXNME!#

To handle the command, you must get its content and convert it to JSON format. Commands are located in-between controlling phrases #!NGINXNMS!# and #!NGINXNME!#.

Starting from server version 4, use GET parameter &format=json when connecting and receiving commands. This parameter will be passed to you in JSON format:

[
    {"id":320146,"mid":"14526134350000000000320146","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"672","time":"Thu, 29 Jun 2017 09:50:16 GMT","text":{...},"extra":{...}}},
    {"id":320147,"mid":"14526134350000000000320147","channel":"6221e0eb48981fce67cf4756e82e8102","tag":"673","time":"Thu, 29 Jun 2017 09:50:17 GMT","text":{...},"extra":{...}}}
]

JSON command structure has the following unified look:

{
    "id" : 320146,
    "mid" : "14526134350000000000320146",
    "channel" : "6221e0eb48981fce67cf4756e82e8102",
    "tag" : "672",
    "time" :"Mon, 03 Oct 2017 06:36:01 GMT",
    "text" : {
        "module_id" : "main",
        "command" : "user_online",
        "params" : {
            ...
        },
    "extra" : {
        "server_time": "2017-10-03T08:36:01+02:00",
        "server_time_unix": 1507012561,
        "server_time_ago": 0,
        'revision': 16,
		'revisionMobile': 1,
        "channel" : "6221e0eb48981fce67cf4756e82e8102"
    }
}

Where:

  • id - message ID
  • mid - message ID (only for server version 3 and higher. Restores history from the moment of a specific message)
  • channel - channel ID (only for server version 3 and higher. Use extra channel for earlier versions)
  • tag - E-tag (only for server version 2 and lower. Restores history from the moment of a specific message)
  • time - message time (only for server version 2 and lower. Restores history from the moment of a specific message)
  • text - structure describing a command action. Contains the following keys:
    • module_id - module ID that sends a command (for marketplace applications - appId)
    • command - command ID
    • params - additional data for executing a command
  • extra - structure describing additional data:
    • server_time - Server time when command created (ATOM format)
    • server_time_unix - Server time when creating command (in Unix timestamp format with browser hour zone)
    • server_time_ago - Number of seconds expired from the moment of command sending
    • server_name - server name that sends command
    • revision - push & pull module revision for browser script
    • revisionMobile - push & pull module revision for mobile client
    • channel - channel ID (only for server version 1)

  Error handling

Various errors can occur when handling server. Its important to process errors correctly to avoid being blocked for possible suspicious activity.

When server connection results in errors, incrementally increase connection time:

  • When error occurs for the first time, connection delay - 100ms.
  • During repeated error - 15 seconds.
  • From 3 to 5 errors - 45 seconds.
  • From 5 to 10 errors - 10 minutes.
  • More than 10 errors in succession - 1 hour.

When errors occur more than 4х times during websocket handling, it's recommended to start using Long polling. Most likely is the situation when client's computer has websocket protocol blocked (exit code websocket 1006 and 1008).

Full transition to the Long polling is reasonable when you weren't able to connect to websocket at all. In cases, when previously you had successful connections, its reasonable to temporarily switch to Long polling for 10 - 30 minutes.

  Format of incoming commands for managing the connection

To successfully manage Push & Pull protocol, ensure processing of control commands.

channel_expire

Command for expiration of channel worktime.

{
    "module_id" : "pull",
    "command" : "channel_expire",
    "params" : {
        "action" : "reconnect",
        "channel" : {
            "id" : "46a437d2336d4a88e4e9b3cd956ecf45.7910bb25e660bf211fdec15e33c5e25e4c3b644a",
            "type": "shared"
        },
        "new_channel": {
            "id": "fb9f7e13dc3d595c5aefe1a0216c27a2.2887eebc6ae160713a732893462dce9d8e23a7b0",
            "start": "2017-06-28T09:57:48+02:00",
            "end": "2017-06-28T21:57:48+02:00",
            "type": "shared"
        }
    }
}

Parameters

ParameterDescription
action Description of required action.
channel Channel information that receives command.
new_channel Information about new channel. Available only if action == reconnect.

Command handling

In case of channel_expire command, depending on the value action, execute:

  • When action == reconnect, use the new_channel data to replace information about current channel channel contains information on which channel is currently in use > . Next, re-establish server connection again.
  • If action == get_config, disconnect from server, request new data on channels via REST pull.application.config.get. Then, re-establish server connection again.

config_expire и server_restart

Command for server settings update

{
    "module_id" : "pull",
    "command" : "config_expire",
    "params" : {}
}

Command handling

In case of config_expire or server_restart commands, disconnect from server and after arbitrary period of time (from 10 to 120 seconds), request new channel data via REST pull.application.config.get. Then, re-establish server connection.




Courses developed by Bitrix24