Этот запрос выполняется из клиентского приложения или из браузерного JavaScript кода. Также можно воспользоваться npm-пакетом xiva-websocket.
Возможны два способа авторизации: через секретный ключ, который можно получить в /v2/secret_sign/v2/secret_sign, и через паспортную куку (поддерживается мультиавторизация).
Параметр | Значение |
service | |
user | |
service | |
topic | |
user | |
client | |
session | |
sign | |
ts | |
sign | |
ts | |
fetch_history или try_fetch_history |
Сервер поддерживает все существующие версии протокола WebSocket. Это самостоятельный протокол над HTTP, поэтому при успешном соединении вы всегда получите HTTP код 101 Switching Protocols. В JavaScript коде обязательно добавляйте обработчик события onclose, чтобы получать сообщения об ошибках.
Параметры client и session не являются обязательными, однако мы рекомендуем их передавать в целях сбора статистики и удобства отладки.
пример пользовательского уведомления{ "version": "1", "uid": "vasya", "service": "mail", "operation": "event", "lcn": "", "session_key": "", "server_notify_id": "context_id:transit_id:client:service", "bright": true, "message": "Привет!", "tags": [], "position": 1 }
Сервер может присылать служебные уведомления. После успешного подключения и проверки авторизации вы получите одно из таких уведомлений - ping от сервера в формате JSON. Оно означает, что соединение до транспорта в порядке. В браузерном JavaScript вы не всегда можете узнать о том, что соединение утеряно — для таких случаев в сообщении есть ключ server-interval-sec. Если в течение указанного интервала вы не получили следующий ping, то можно считать, что соединение было утеряно — подключитесь заново.
пример ping уведомления{ "operation": "ping", "server-interval-sec": 60, "message": "" }
Факт установки соединения и смены протокола не означает, что вы успешно подписались. Между подключением и фактической подпиской может пройти какое-то время. Это зависит от многих факторов, например, связности сети или задержек БД. Поэтому отдельно для каждой пары (user, service) по факту подписки придет служебное уведомление subscribed (это сообщение включается индивидуально для каждого сервиса, по умолчанию выключено).
пример subscribed уведомления{ "uid": "vasya", "service": "mail", "operation": "subscribed", "event": "subscribed", "message": "" }
Параметр fetch_history позволяет получить пропущенные из-за разрыва сети или засыпания устройства уведомления. Если история за время отсутствия ушла далеко вперед, то позиция подписки, которую вы передали, будет скорректирована сервером так, чтобы вы получили не больше count уведомлений. На запрос с fetch_history сервер пришлет служебное уведомление.
пример fetch_history уведомления{ "user": "vasya", "service": "mail", "operation": "precise-position", "position": 1, "count": 9 }
Оно означает, что подписка успешно создана с позиции position и прямо сейчас на клиент будут доставлены не больше count уведомлений. Если уведомления нужны вам только при условии, что в истории не больше count сообщений от указанной позиции, то вместо fetch_history передайте try_fetch_history с тем же значением. В этом случае сервер не будет присылать все уведомления, если их больше, чем запросил клиент. Вместо этого будет сформировано служебное уведомление precise-position. В нем будет count 0 и позиция в конце истории. Достаточно вычесть позицию клиента из этого числа, чтобы узнать количество пропущенных уведомлений.
коды закрытия соединенияКод | Сообщение | Описание |
1000 | Штатное закрытие соединения. | |
4400 | { "error" : "описание ошибки" } | Ошибка в запросе. |
4401 | { "error" : "описание ошибки" } | Ошибка авторизации. |
4500 | { "error" : "описание ошибки" } | Внутренняя ошибка сервера. |
Существует ряд других служебных сообщений. Все они имеют ключи operation и message. В клиентском коде рекомендуем игнорировать неизвестные типы сообщений, а также следовать принципам защитного программирования при парсинге и обработке всех сообщений.