Introduction#
Privicore uses WebSockets to provide real-time notifications for asynchronous operations. A separate WebSocket proxy server subscribes to message queues and delivers notifications directly to connected clients, enabling immediate updates without the need for polling.What Are WebSockets in Privicore?#
WebSockets provide a persistent, bidirectional communication channel between clients and Privicore, enabling:Real-time Command Status Updates: Receive immediate notifications when asynchronous commands complete (profile registration, device approval, policy activation, etc.)
Data Download Links: Get download links instantly when requested data via token becomes available
Architecture Overview#
Message Flow#
Privicore Operation (Async) → RabbitMQ Queue → WebSocket Server → Connected Client
Components#
1.
Privicore Backend: Processes operations asynchronously and publishes completion messages to RabbitMQ
2.
RabbitMQ: Message queue system with user-specific queues for routing messages
3.
WebSocket Proxy Server: Separate Node.js server that subscribes to user queues and forwards messages to connected WebSocket clients
4.
Client Application: Connects via WebSocket and receives real-time notifications
How It Works#
User-Specific Queues#
Each profile has a dedicated message queue in RabbitMQ. When asynchronous operations complete:1.
Privicore publishes a message to the user's queue
2.
WebSocket proxy server, subscribed to that queue, receives the message
3.
Server forwards the message to all WebSocket clients connected with that user's authorization token
4.
Client receives the message in real-time
Message Types#
Privicore sends two types of messages via WebSocket:Command Status Messages#
Notifications about asynchronous command completion. These messages inform you when operations like profile registration, device approval, or data token exchange have finished processing.Use Case: After initiating profile registration, receive immediate confirmation when registration completes instead of repeatedly checking status.Data Download Messages#
Notifications containing download links for data requested via data tokens. When you request data using a token, the system prepares the data and sends a download link via WebSocket.Use Case: After requesting data via token, receive the download URL immediately when data is ready, enabling automatic download initiation.Why Use WebSockets?#
Without WebSockets (Polling)#
Traditional approach requires repeated API calls to check status:Client → Check Status → Not Ready
(wait 2 seconds)
Client → Check Status → Not Ready
(wait 2 seconds)
Client → Check Status → Ready!
With WebSockets (Real-Time)#
WebSocket approach provides immediate notification:Client → Subscribe to WebSocket → Wait
↓
Message Arrives → Process Immediately
Connection Requirements#
To connect to the WebSocket server, you need:WebSocket server address and port
Valid profile authorization token (obtained from authentication)
WebSocket client library (e.g., ws for Node.js, native WebSocket API for browsers)
{
"data": {
"type": "MESSAGE_TYPE",
"id": "unique-identifier",
"command_status": 2,
"body": "message content or download link"
}
}
type field indicates the message category, id is the unique identifier for tracking, and body contains the actual content.Use Cases#
Asynchronous Command Tracking#
Track completion of operations that take time to process:Data Retrieval#
Receive download links for data requested via tokens:Request data using data token
System prepares encrypted data
Download link delivered via WebSocket
Begin download immediately
Security Model#
WebSocket connections require valid profile authorization tokens
Messages are routed only to clients authenticated with the correct token
Each profile receives only their own messages - no cross-profile access
Tokens should be transmitted during channel join, not in connection URL
Use secure WebSocket (wss://) in production environments
Getting Started#
To integrate WebSockets into your application:1.
Establish Connection: Connect to the WebSocket server
2.
Join Channel: Authenticate and subscribe to your profile's message queue
3.
Handle Messages: Process incoming command status and data download messages
4.
Leave Channel: Unsubscribe when disconnecting
