Собственный Push&Pull клиент

В этой статье вы найдете информацию как написать свой собственный клиент. Если вам не нужен новый клиент, а нужно просто добавить функционал интерактивности в уже существующее приложение, то вам будет полезна статья Push&Pull в браузере.

С помощью подключения к RT-серверам создаётся действительно интерактивное приложение: меняется состояние приложения, мгновенно обновляется интерфейс без необходимости ajax запросов.

Разработка приложенияРазработка приложения

Для работы с сервисом есть два способа подключения: Long polling и Websocket.

Основным методом подключения рекомендуется использовать websocket. Long polling используется только для устройств у которых нет поддержки websocket, или если при подключении к websocket у клиента часто возникают проблемы.

Для получения данных о сервере и адресах подключения используйте REST команду pull.application.config.get

Для подключения к серверу, возьмите в настройках сервера (поле server) адрес подключения нужного типа (например, websocket_secure) и добавьте к нему все доступные каналы через /. В случае, если на портале используется облачный push-сервер, к URL'у для подключения к серверу необходимо добавить параметр clientId.

Пример подключения для websocket для облачного push-сервера:

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

Пример подключения для websocket для коробочного push-сервера:

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

Время работы каждого канала ограничено 12 часами. Необходимо отслеживать время окончания и делать повторный запрос к pull.application.config.get когда у одного из каналов завершилось время работы.

Для доступа к истории в канале к указанному выше адресу добавьте специальные get-метки: &tag= и &time= (для версии сервера 2 и ниже) или &mid= (для версии 3 и выше). Все необходимые данные для get-меток вы получите при разборе каждой команды из канала. После подключения с данными метками, вам будут одноразово доступны сообщения, которые для текущей сессии не были доступны.

Общий формат команд от сервераОбщий формат команд от сервера

Для сервера версии 3 и ниже при поступлении команд, приходит текст вида:

#!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!#

Для работы с командой, необходимо получить её содержимое и преобразовать в JSON. Текст команды располагается между управляющими фразами #!NGINXNMS!# и #!NGINXNME!#.

Начиная с версии сервера 4, используйте добавление GET-параметра &format=json при подключении и при поступлении команд, он будет вам отдан в формате JSON:

[
    {"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 структура команды имеет следующий унифицированный вид:

{
    "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"
    }
}

Где:

• id — идентификатор сообщения
• mid — идентификатор сообщения (только для версии сервера 3 и выше, используется для восстановления истории с определенного сообщения)
• channel — идентификатор канала (только для версии сервера 3 и выше, для более ранних используйте extra.channel)
• tag — E-tag (для версии сервера 2 и ниже, используется для восстановления истории с определенного сообщения)
• time — время сообщения (для версии сервера 2 и ниже, используется для восстановления истории с определенного сообщения)
• text — структура, описывающая действие команды, содержит следующие ключи:
  • module_id — идентификатор модуля, отправившего команду (для приложений marketplace — appId)
  • command — идентификатор команды
  • params — дополнительные данные для выполнения команды
• extra — структура, описывающая дополнительные сведения:
  • server_time — время сервера на момент формирования команды (формат ATOM)
  • server_time_unix — время сервера на момент формирования команды (в формате Unix timestamp с часовым поясом браузера)
  • server_time_ago — количество секунд, прошедших с момента отправки команды
  • server_name — имя сервера, отправившего команду
  • revision — ревизия модуля push & pull для браузерного скрипта
  • revisionMobile — ревизия модуля push & pull для мобильного клиента
  • channel — идентификатор канала (только для версии сервера 1)

Работа с ошибкамиРабота с ошибками

Во время работы с сервером могут возникать разные ошибки. Во избежания блокировки за подозрительную активность важно правильно их обрабатывать.

Если подключение к серверу приводит к ошибкам, необходимо инкрементально увеличивать время подключения:

• При возникновении ошибки в первый раз, задержка при подключении - 100мс.
• При повторной ошибке - 15 секунд.
• От 3 до 5 ошибок - 45 секунд.
• От 5 до 10 ошибок - 10 минут.
• Более 10 ошибок подряд - 1 час.

При работе с websocket при возникновении ошибок более 4х раз, рекомендуется переходить на работу с Long polling. Очень вероятна ситуация, что на компьютере клиента заблокирована работа websocket протокола (код завершения websocket 1006 и 1008).

Полный переход на Long polling, имеет смысл если вы ни разу не смогли подключится по websocket. Если ранее были успешные подключения, то имеет смысл переключится временно, на 10 – 30 минут.

Формат поступающих команд для управления подключениемФормат поступающих команд для управления подключением

Для собственной реализации работы с протоколом Push & Pull предусмотрите обработку управляющих команд.

channel_expirechannel_expire

Команда об истечении времени работы канала.

{
    "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"
        }
    }
}

Параметры командыПараметры команды

Описание работы с командойОписание работы с командой

При поступлении команды channel_expire, в зависимости от значения action, выполните следующие шаги:

• action == reconnect
  • данными из new_channel замените информацию о текущем канале
  • переустановите подключение к серверу заново
• action == get_config
  • отключитесь от сервера
  • запросите новые данные о каналах через REST pull.application.config.get
  • установите подключение к серверу заново

config_expire и server_restartconfig_expire и server_restart

Команда о изменении настроек сервера.

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

Описание работы с командойОписание работы с командой

Если поступила команда config_expire или server_restart:

• отключитесь от сервера
• через случайный промежуток времени (от 10 до 120 секунд) запросите новые данные о каналах через REST pull.application.config.get
• установите подключение к серверу заново