Интерактивные приложения

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

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

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

Для работы с сервисом есть два способа подключения: Long polling и websocket Когда пользователь входит на сайт, его браузер, настольное или мобильное приложение устанавливают и держат постоянное соединение с Push-сервером.
Обычно это делается с помощью WebSocket , который используют 95% современных браузеров. А если технология WebSocket не поддерживается браузером, то используется Long Polling — постоянный долгий опрос.

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

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

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

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

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

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

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

Время работы каждого канала ограничено 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_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"
		}
	}
}

Параметры

Параметр Описание action Описание необходимого действия. channel Информация о канале для которого получена команда. new_channel Информация о новом канале. Доступна только если action == reconnect.

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

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

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

config_expire и server_restart

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

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

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

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