Bitrix Framework

Subscription

Starting from pull version 18.5.7 (for desktop computers) and mobile 18.5.10 (for mobile devices) developers can connect to Push & Pull module events using the method BX.PULL.subscribe. Directions on how to handle this method are provided below.

  Connecting the library

Check if Push & Pull module is available for components used only in browser. Connect the library pull.client:

• Indicate CoreJS pull.client dependency in description of your extension or call \Bitrix\Main\UI\Extension::load('pull.client');

Connect the required dependencies for your context within components used in a mobile application.

• For the web page, indicate CoreJS mobile.pull.client dependency in the description for extension or call \Bitrix\Main\UI\Extension::load('mobile.pull.client');
• For JaNative component, indicate the dependency pull/client/events in the file deps.php.
• For Offline WebComponent indicate the dependency pull/client/events in the file config.php in "deps" section.

Within mobile extension, use the methods:
BX.PULL.subscribe(...),
BX.PULL.extendWatch(...),
BX.PULL.clearWatch(...),
BX.PULL.capturePullEvent(),
BX.PULL.getDebugInfo().

There are three formats for subscription, you can select a suitable format depending on your tasks.

  Single command

Subscription for a single command:

BX.PULL.subscribe({
	type: BX.PullClient.SubscriptionType.Server,
	moduleId: 'im',
	command: 'messageChat',
	callback: function (params, extra, command) {
		console.warn('Receive message:', params.message.text)
	}.bind(this)
});

Where:
type - subscription type (Server, Client, Online) - may be skipped, Server type is set by default,
moduleId - module that sent the command
command - subscribed command
callback - handler function.

The following parameters for the method called upon event:

• params - object, command parameters,
• extra - object, additional data, such as module version, server name and time, time elapsed since sent command,
• command - string, command name.

Method result is the function that can be used to unsubscribe from specified command in the future:

let unsubscibe = BX.PULL.subscribe({...}); // subscription
unsubscibe(); // unsubscription

  Several commands

Subscription to multiple commands via router function:

BX.PULL.subscribe({
	type: BX.PullClient.SubscriptionType.Server,
	moduleId: 'im',
	callback: function (data) {
		if (data.command == 'messageAdd')
		{
			this.doSomething();
		}
	}.bind(this)
});

Where:
type - subscription type (Server, Client, Online) - may be skipped, Server type is set by default,
moduleId - module that sent the command
callback - handler function for all incoming commands.

The parameter data in the specified callback function will contain the following object:

{
	command: '...', // command name
	params: {...}, // command parameters
	extra: {...} // additional data, such as module version, server name and time, 
}

Method result is the function that can be used to unsubscribe from module commands in the future.

let unsubscibe = BX.PULL.subscribe({...}); // subscription
unsubscibe(); // отписка

  Router class

Subscription via router class:

BX.PULL.subscribe(new CommandHandler(options));

You can pass the link to the objects you need in options, for example: for current context, to be able to call methods from your base class (if required) within handler class.

The router class itself looks as follows (please note: class is written in ES6; class applications in format ES5 is possible as well)

class CommandHandler
{
	constructor(options = {})
	{
	}

	getModuleId()
	{
		return 'im';
	}

	getSubscriptionType()
	{
		return BX.PullClient.SubscriptionType.Server;
	}
	
	getMap()
	{
		return {
			message: this.handleMessage.bind(this), 
			messageChat: this.handleMessageChat.bind(this),
			startCall: this.handleStartCall.bind(this),
		}; 
	}

	handleMessage(params, extra, command)
	{
		console.log('exec command - message', params);
	}

	handleMessageChat(params, extra, command)
	{
		console.log('exec command - messageChat', params);
	}

	handleStartCall(params, extra, command)
	{
		console.log('exec command - startCall', params);
	}
}

Method getModuleId() returns module ID, which commands must be processed by this class. (Required method).

Method getSubscriptionType() returns subscription type (Server, Client, Online). (Optional method, if not specified, sets as Server type)

Method getMap() returns map of command received from server and method that will process it.

  Object formats

Possible object formats are returned by the function getMap().

The recommended function link format, i. e. IDE may quickly switch to function by just clicking on it:

{
	startCall: this.handleStartCall.bind(this),
}

The string format:

{
	startCall: 'handleStartCall',
}

In callback function format:

{
	startCall: function(params, extra, command) {
		console.log('exec command - startCall', params);
	}.bind(this),
}

Parameters for the method called upon triggered event are as follows:

• params - object, command parameters
• extra - object, additional data, such as module version, server name and time, time elapsed from sent command
• command - string, command name

Simplified description variant

You can simplify class description by skipping getMap() method description. Then command processing methods must start from the word handle. After that, it must contain command name with first letter is the capital letter: for example, startCall command, and class must contain the method handleStartCall.

class CommandHandler
{
	constructor(options = {})
	{
	}

	getModuleId()
	{
		return 'im';
	}

	handleMessage(params, extra, command)
	{
		console.log('exec command - message', params);
	}

	handleMessageChat(params, extra, command)
	{
		console.log('exec command - messageChat', params);
	}

	handleStartCall(params, extra, command)
	{
		console.log('exec command - startCall', params);
	}
}

Method result is the function that can be used to unsubscribe from module commands in the future.

let unsubscibe = BX.PULL.subscribe({...}); // подписка
unsubscibe(); // отписка

Description hybrid variant

You can simultaneously use getMap() and methods governed by CommandHandler naming standards. Such variant will be suitable, if you want to make alias to the deprecated command format or if you are sending commands in the format that is impossible to describe in method name.

class CommandHandler
{
	constructor(options = {})
	{
	}

	getModuleId()
	{
		return 'im';
	}
	
	getMap()
	{
		return {
			'Application::send': this.handleApplicationSend.bind(this),
			messageChatAdd: this.handleMessageChat.bind(this) 
		}; 
	}

	handleMessage(params, extra, command)
	{
		console.log('exec command - message', params);
	}

	handleMessageChat(params, extra, command)
	{
		console.log('exec command - messageChat', params);
	}

	handleStartCall(params, extra, command)
	{
		console.log('exec command - startCall', params);
	}
	
	handleApplicationSend(params, extra, command)
	{
		console.log('exec command - applicationSend', params);
	}
}

Method result is the function that can be used to unsubscribe from module command in the future:

let unsubscibe = BX.PULL.subscribe({...}); // subscription
unsubscibe(); // unsubscription