Модуль Push and Pull pull передает команды от серверного кода клиентскому приложению. Он нужен, когда открытая страница должна отреагировать на изменение данных: обновить статус операции, счетчик или карточку объекта без перезагрузки страницы.

Например, пользователь запустил подготовку отчета и продолжил работать на странице. Когда отчет готов, сервер сообщает об этом браузеру, и страница показывает результат. Если отчет открыли несколько участников, уведомление может получить каждый из них.

Назначение модуля и выбор сценария

Сначала определите, где пользователь должен увидеть результат и насколько быстро интерфейс должен узнать об изменении.

|

|| Задача | Подход | Что учесть || || Обновить открытую страницу после изменения на сервере | Pull-команда и JS-обработчик | Нужны работающий транспорт и подготовленный клиент || || Периодически проверять состояние, если задержка допустима | HTTP-запросы к API модуля, который хранит данные | Приложение выбирает интервал, ограничивает число запросов и обрабатывает ошибки || || Получить результат действия, которое выполняется в текущем запросе | Ответ HTTP-запроса | Отдельная команда нужна, если об изменении должны узнать другие клиенты или результат появится позже || || Показать уведомление на телефоне | Мобильное push-уведомление | Нужны настроенная отправка и приложение на устройстве, которое принимает уведомления || || Создать уведомление в мессенджере продукта | API модуля мессенджера | Модуль мессенджера отвечает за содержимое и поведение уведомления || |#

Pull-команда — сообщение с именем действия и данными для клиентского обработчика. Команда не создает визуальное уведомление. JavaScript может изменить текст на странице, запросить свежие данные или показать сообщение пользователю.

Мобильное push-уведомление — отдельный сценарий доставки на устройство. Получение команды открытой веб-страницей не подтверждает, что уведомление появилось на телефоне. Подготовьте отправку на устройство по статье Отправка мобильных push-уведомлений.

Push and Pull доставляет сообщения клиентам. Сохранение объектов, проверка прав доступа, история изменений и запуск фоновых операций остаются задачами приложения.

Путь сообщения и основные понятия

Сервер очередей — служба доставки команд от приложения подключенным клиентам. В этой схеме он принимает сообщения от PHP-приложения и передает их браузерам. Фоновые PHP-задачи выполняет код приложения.

Для работы такой схемы нужны установленный модуль pull, настроенный сервер очередей и подключенный JS-клиент на странице. Проверяйте отдельно два направления связи: публикацию команды с сервера приложения и получение команды браузером.

Код приложения сохраняет изменение
→ PHP API модуля pull подготавливает команду для получателей
→ сервер приложения публикует команду на сервере очередей
→ сервер очередей передает команду подключенному браузеру
→ JS-клиент вызывает подходящий обработчик
→ обработчик обновляет интерфейс или запрашивает данные

Например, фоновая операция формирует отчет. Приложение сохраняет результат и отправляет команду о готовности. Браузер получает идентификатор отчета, запрашивает его состояние и показывает ссылку на файл. Саму операцию запускает и выполняет код приложения. Сервер очередей передает сообщение о результате.

Команда, канал и тег

Команда связывает серверный и клиентский код через согласованный набор полей.

|

|| Поле | Назначение | Пример || || module_id | Указывает модуль, который отправляет команду | example.reports — собственный модуль отчетов || || command | Задает имя действия для клиентского обработчика | reportReady — отчет подготовлен || || params | Содержит данные, которые нужны обработчику | reportId — идентификатор подготовленного отчета || |#

Имена модуля и команды должны быть согласованы у отправителя и обработчика. В параметрах JS-подписки идентификатор модуля называется moduleId.

Канал — адрес доставки на уровне транспорта. При адресной отправке код приложения задает получателя через API модуля. Общий канал предназначен для рассылки всей его аудитории.

Тег наблюдения — строковая метка, по которой приложение объединяет пользователей, ожидающих определенное изменение. Например, тег REPORT_42 можно выбрать для наблюдения за отчетом с идентификатором 42. Формат такой метки задает приложение.

Подписчик тега — пользователь, для которого серверный код зарегистрировал наблюдение. Отправка по тегу позволяет уведомить наблюдателей без самостоятельного составления списка при каждом изменении.

Подключение и два вида подписки

В сценарии получения команды участвуют разные механизмы.

|

|| Механизм | За что отвечает | Чего недостаточно для полного сценария || || Подключение JS-клиента к серверу очередей | Обеспечивает связь для получения сообщений | Соединение не задает действие интерфейса || || Серверное наблюдение через CPullWatch::Add | Включает пользователя в число получателей команд по тегу | Наблюдение не регистрирует JavaScript-функцию на странице || || JS-подписка через BX.PULL.subscribe | Выбирает обработчик полученной команды | Регистрация обработчика не создает серверное наблюдение по тегу || |#

При отправке конкретному пользователю серверное наблюдение по тегу не требуется. Для отправки наблюдателям нужны и серверная регистрация по тегу, и клиентский обработчик.

Каналы и выбор получателей

Выбирайте получателей по смыслу изменения и доступу к данным. Идентификатор модуля и имя команды помогают обработать сообщение, но не заменяют выбор аудитории на сервере.

|

|| Получатели | Классический PHP API | Когда использовать || || Один пользователь | CPullStack::AddByUser | Сообщить инициатору о готовности его отчета || || Список пользователей | CPullStack::AddByUsers | Уведомить заранее определенных участников || || Аудитория общего канала | CPullStack::AddShared | Передать общедоступное изменение || || Пользователи, наблюдающие за тегом | CPullWatch::AddToStack | Обновить объект у его наблюдателей || |#

Выберите получателей и состав команды по примерам из статьи Отправка команд из PHP.

Общий канал работает только при использовании сервера очередей. Передавайте через него только данные, доступные всей аудитории канала. Фильтрация команды в JavaScript происходит после получения сообщения и не защищает его содержимое.

Для адресной отправки проверяйте права выбранных пользователей на передаваемые данные. Для наблюдения по тегу проверяйте доступ перед регистрацией и учитывайте последующее изменение прав. Название тега не является разрешением на чтение объекта. Если команда содержит только идентификатор для повторного запроса, API чтения также должно проверить доступ.

Неавторизованные посетители

В схеме персональной гостевой адресации приложение использует отрицательный идентификатор посетителя. Если CPullChannel::Get() проверяет наличие активной учетной записи для получателя, персональный канал для отрицательного гостевого ID недоступен. Отрицательный идентификатор не соответствует учетной записи. В такой реализации для личного результата используйте авторизацию. Общий канал может входить в конфигурацию гостевого клиента, но подходит только для общедоступных данных.

Опция гостевого режима доступна при установленном модуле Веб-аналитика statistic. Метод CPullOptions::GetGuestStatus() проверяет и опцию, и наличие модуля. Включение этой опции не устраняет ограничение персонального канала.

Примечание

Проверить канал и учесть смену авторизации помогут примеры из статьи Отправка команд из PHP. В гостевом сценарии важно различать двух посетителей и сохранять правильную адресацию при повторном открытии страницы, входе и выходе из учетной записи.

Жизненный цикл и границы доставки

Вызов отправки, передача команды браузеру и изменение интерфейса — отдельные этапы. Проверяйте каждый из них, если результат важен для приложения.

От подготовки команды до обработки

PHP-код может добавить команду к отправке раньше, чем модуль передаст ее серверу очередей. При отложенной отправке модуль накапливает команды и планирует их передачу через Application::addBackgroundJob. Приложение выполняет эту задачу при штатном завершении. Для обычной страницы нужно пройти эпилог — завершающий этап обработки страницы Bitrix Framework.

Для AJAX-обработчика, агента и скрипта командной строки нужны разные способы завершения. Выберите подходящий вариант в статье Отправка команд из PHP.

|

|| Этап | Что проверять | Что еще не подтверждено || || Вызов PHP API | Результат вызова и ошибки по контракту выбранного метода | Получение команды браузером || || Публикация на сервере очередей | Успех передачи со стороны приложения | Выполнение клиентского обработчика || || Получение клиентом | Поступление нужной команды с ожидаемыми данными | Успешное обновление интерфейса || || Обработка в JavaScript | Изменение интерфейса либо результат дополнительного запроса | Ознакомление пользователя с результатом || |#

Отправляйте сообщение об изменении после успешного сохранения данных. Если сохранение входит в транзакцию, учитывайте ее завершение: клиент, получивший команду раньше фиксации, может прочитать прежнее состояние. Пример такой интеграции приведен в статье Обновление компонента после фоновой операции.

Сроки жизни и восстановление состояния

Различайте срок жизни канала, срок хранения сообщения и срок серверного наблюдения по тегу. Продление наблюдения не означает продление хранения уже отправленных команд.

Канал имеет собственный срок жизни. Когда он истекает, клиент получает новые параметры подключения. Поэтому не сохраняйте адрес канала как постоянный идентификатор пользователя. После переподключения перечитайте состояние объекта.

Срок сообщения expiry относится к публикации на сервере очередей. Он не продлевает канал и не гарантирует доставку команды. Новая подписка также не восстанавливает пропущенное сообщение. Результат операции сохраняйте в приложении.

Наблюдение по тегу клиент поддерживает через extendWatch, а просроченные записи удаляет агент. Запуск агента может задержаться. При отзыве прав удалите подписку явно и проверяйте доступ при чтении данных. Подробнее — в статье Подписки по тегам.

Для устойчивого интерфейса предусмотрите следующие действия:

При открытии страницы загружайте текущее состояние объекта. Учитывайте изменение между первым чтением и готовностью получения команд.
После разрыва и восстановления связи повторно сверяйте состояние с сервером.
Делайте обработку повторной команды безопасной: повторное чтение состояния не должно повторно запускать бизнес-операцию.
Учитывайте конкурирующие ответы на запросы, чтобы более раннее состояние не заменило новое.
Ограничивайте ожидание фоновой операции. Если команда не пришла, проверяйте сохраненный результат отдельным запросом.

Перечисленные меры помогают интерфейсу восстановить состояние, но не дают гарантий доставки каждой команды, фиксированной задержки или обработки ровно один раз. Соберите пример и проверьте пропущенное уведомление по статье Обработка команд в JavaScript.

Маршрут по разделу

Сначала подготовьте окружение по статье Настройка модуля и сервера очередей. Затем соберите отправку и получение команды по статье Обновление страницы по команде сервера. Если окружение уже настроено, переходите сразу к примеру.

Далее переходите от отдельных частей обмена к обновлению компонента.

Отправка команд из PHP — выбор получателей, данные команды и момент отправки.
Обработка команд в JavaScript — регистрация обработчиков, загрузка состояния и восстановление после разрыва.
Подписки по тегам — наблюдение за объектом, продление и прекращение подписки.
Обновление компонента после фоновой операции — связь сохраненного результата с состоянием интерфейса.

Для уведомлений на телефон предусмотрена отдельная ветка Отправка мобильных push-уведомлений. Проверки сбоев доставки описаны в статье Диагностика и обслуживание Push and Pull.