Views: 3523 (Data available since 06.02.2017)

The Push and Pull module is used to broadcast messages and notifications to website clients. Because this feature is implemented as a stand-alone module, any other module, standard or custom, can send messages to clients using the module API calls.

This module is imperative for fully functional operation of the modules Mobile Application, Blogs and Web Messenger.

The module is built around the following technologies.

Pull (or client pull) is a style of network communication where the initial request for data originates from the client, and then is responded to by the server.

Pull technology is an efficient and low cost method of having a message broadcasted to multiple unknown recipients. It is mostly beneficial to clients looking up for a specific item of data. At present, pull requests form the foundation of network computing where multitudes of clients request data from central servers. An example of application of this kind of network communication is HTTP requests responded to by the websites.

Push is in some sense contrast to pull technology.

Push (or server push) is a style of Internet-based communication where the request for a transaction is initiated by the publishing server according to the client parameters.

A user may subscribe to receive information from a content provider and then have information "pushed" to their computer or mobile device every time such information is available at the server.

How Push and Pull Work?

At the server side, broadcasting instant messages is backed up by the nginx module: nginx-push-stream-module. This module supports long-polling client connections and ensures message delivery.

Note: Bitrix Framework is capable of providing considerably high messaging rate without nginx-push-stream-module: max. interval of 60 seconds, which reduces to 10 seconds if there are pending messages.

When a client opens a page, the former sends an AJAX request to connect to a listening channel on one of the nginx ports: 8893 (http) or 8894 (https). Then, nginx redirects the client to an internal queue server (available only at 127.0.0.1:8895). The server checks the channel for new messages and, if there are none, holds the connection for 40 seconds but does not respond.

If a new message becomes available in the client listening channel within 40 seconds, the server sends it to the client and closes the connection. Otherwise, the server just sends the "304 Not Modified" response to the client and closes the connection.

Once the client has received the server response and the connection is closed, the client can connect again sending the last-modified date and time.

User applications can send messages to the client listening channel by using the Push and Pull module API calls. It is generally recommended to use HTTPS for push and pull communication.

Note: The time at the server must be consistent. Perform time synchronization regularly to ensure correct channel status.

Configuring the Module

If you use Bitrix Framework distributions with BitrixVM or BitrixEnvironment (for Linux) version 5.0 or better, you won't have to configure anything. If you employ some kind of custom installation, the module configuration will require the following steps.

Note: The example provided below is given only as a sample. The configuration of a web project not based on either the BitrixVM or BitrixEnvironment is the sole responsibility of the project’s administrator.

  • Compile nginx enabling nginx-push-stream-module;

    As an example, a file from our virtual machine can be used:

    • /etc/nginx/bx/site_enabled/push.conf – the push and pull settings are for publishing messages as well as for operations with the mobile apps;
    • /etc/nginx/bx/conf/im_subscrider.conf – settings for receiving messages;
    • /etc/nginx/bx/conf/im_settings.conf – number of channels, memory size, etc.

    Parameters for nginx-push-stream-module version 0.4.0 (recommended)

    Parameters for nginx-push-stream-module version 0.3.4

  • Open Settings > System Settings > Module Settings > Push and Pull and enable the option "nginx-push-stream-module is installed on server":

    Select the virtual machine version you are using. The recommended version is 4.4 or higher because it includes a newer version of nginx-push-stream-module (0.4.0) which enables web sockets and command sending.

  • When setting the value of Maximum number of commands to send while connected to server, remember that it depends on nginx's large_client_header_buffers parameter. When the latter is set to 8 KB, the maximum number of commands is 100. These two values are directly proportional; if your requirement is to send 200 commands while connected, set large_client_header_buffers to 16 KB. In general, the more the average number of possible message recipients, the more the value of Maximum number of commands to send… field should be. While this parameter is directly related to the total intranet users, you will have to find the value that suits your conditions best experimentally. If you have powerful hardware, you could just allow an ample load margin and be on the safe side: use 100 command for 150 users, 200 commands for 300 users and so on.
  • Override the URL templates if so required. For multiple domain configurations, use #DOMAIN# macro as the domain name in the message view URL: it will be replaced with an appropriate domain name automatically. Example: http://#DOMAIN#:8893/bitrix/sub/

    Note: If your configuration of nginx-push-stream-module is similar to that of BitrixEnvironment, you won't have to edit these URL's.

  • If you intend to communicate with mobile devices, check the option Send PUSH notifications to mobile devices.
  • If the system manages multiple active sites, you can enable or disable the module for each site individually.
Note: the module supports web sockets since version 14.1.2. This option is only available if a corresponding parameter is enabled in nginx-push-stream-module.

Attention! If you get an error like
XMLHttpRequest cannot load http://example.com:8893/bitrix/sub/?CHANNEL_ID=123a27000bed7ee1ffd6935e063df0cf/c15e31dfc968de41b032474d8d651b77&tag=1&rnd=1380619831146. Origin http://example.com is not allowed by Access-Control-Allow-Origin.
your push-stream-module version is below 0.3.4.

To eliminate the error, please update the module or comment out the following lines:

add_header "Access-Control-Allow-Origin" "*";
add_header "Access-Control-Allow-Headers" "if-modified-since, origin, if-none-match";



Courses developed by «Bitrix», Inc.