Push&Pull в браузере

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Штатный клиент BX.PullClient держит соединение с серверами Push&Pull и передает в браузер события, которые серверная часть приложения отправляет методом pull.application.event.add. Интерфейс приложения обновляется сразу, без опроса сервера и перезагрузки страницы.

Клиент работает на странице приложения и сам запрашивает конфигурацию заново, когда срок канала истекает. Если приложение работает отдельно от интерфейса Битрикс24 и штатного клиента недостаточно, соединение придется поддерживать самостоятельно — это описывает статья Собственный Push&Pull клиент.

Клиент работает только в контексте приложения. Конфигурацию подключения он запрашивает методом pull.application.config.get, которому нужен OAuth-токен и scope pull, а вебхук такой контекст не создает.

Что нужно перед началом

Для клиента нужны две библиотеки с api.bitrix24.tech: api/v1/ дает объект BX24 для вызовов REST, api/v1/pull/ — конструктор BX.PullClient.

Как подключить клиент

  1. Подключите библиотеки api/v1/ и api/v1/pull/ в <head> страницы
  2. Дождитесь готовности BX24: остальные шаги выполняйте внутри BX24.init
  3. Получите идентификатор пользователя методом user.current
  4. Создайте клиент через new BX.PullClient() и передайте параметры
  5. Подпишитесь на события методом subscribe
  6. Запустите соединение методом start
<!DOCTYPE html>
<html>
<head>
	<title>Bitrix24 application with Push & Pull</title>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<script src="//api.bitrix24.tech/api/v1/"></script>
	<script src="//api.bitrix24.tech/api/v1/pull/"></script>
</head>
<body>
	<script>
		BX24.init(function () {
			BX24.callMethod('user.current', {}, function (result) {
				if (result.error()) {
					console.error(result.error().ex);
					return;
				}

				window.appPullClient = new BX.PullClient({
					restApplication: 'my_app_pull',
					restClient: BX24,
					userId: Number(result.data().ID)
				});

				window.appPullClient.subscribe({
					moduleId: 'application',
					callback: function (data) {
						console.warn(data); // {command: '...', params: {...}, extra: {...}}
					}
				});

				window.appPullClient.start();
			});
		});
	</script>
</body>
</html>

Чтобы убедиться, что клиент получает события, отправьте событие из серверной части методом pull.application.event.add. Обработчик выведет в консоль браузера объект с полями command, params и extra.

Параметры BX.PullClient

Обязательные параметры отмечены *

Название
тип

Описание

restApplication*
string

Идентификатор приложения. Когда он задан, клиент запрашивает конфигурацию методом pull.application.config.get и подключается к каналам приложения. По этому же значению клиент хранит состояние соединения в браузере, поэтому задайте стабильную строку — одну на приложение

restClient*
object

Объект, через который клиент вызывает методы REST. В приложении передайте BX24 из подключенной библиотеки. Без этого параметра клиент создаст собственный объект, а тот авторизуется идентификатором сессии Битрикс24, которого на странице приложения нет

userId*
integer

Идентификатор текущего пользователя. На странице приложения клиенту неоткуда взять его самостоятельно, поэтому значение передают явно — в примере его возвращает user.current

Подписка на события

Метод subscribe регистрирует обработчик и возвращает функцию, которая его отключает:

const unsubscribe = window.appPullClient.subscribe({
	moduleId: 'application',
	callback: function (data) {
		console.warn(data);
	}
});

unsubscribe();

Обязательные параметры отмечены *

Название
тип

Описание

moduleId*
string

Модуль, события которого нужны приложению. События из канала приложения приходят с application — это значение параметра MODULE_ID метода pull.application.event.add

callback*
function

Функция-обработчик. Что она получит, зависит от того, задано ли поле command

command
string

Команда, на которую подписан обработчик, — значение параметра COMMAND метода pull.application.event.add. Без нее обработчик получает все команды модуля

type
string

Источник событий. По умолчанию server — события, которые отправила серверная часть. Для событий приложения менять не нужно

От поля command зависит, в каком виде обработчик получит данные:

  • без command — событие приходит целиком: callback(data, info), где data содержит command, params и extra
  • с command — те же данные приходят разобранными: callback(params, extra, command, info)

Последним параметром обработчик в обеих формах получает info с полями type и moduleId.

Продолжите изучение

Предыдущая
Обзор методов
Следующая
Собственный Push&Pull клиент