Presence

“Being aware of who’s online is the first step toward building truly responsive experiences.”

Presence

How Presence Works

Presence tracks which user IDs are currently connected to a specific channel. After you enable it, each connection notifies others on the same channel when it joins or leaves.

Key points:

• Presence is only available on channels (not direct connections).
• You must enable it in your WebSocket server configuration.
• Each client must send a user ID (e.g., userId) to associate their connection with a specific user in your system. If you don't, the channel will have only awareness of the new connection, but it won't be able to identify who is connected.

1. Enable Presence in the Server

Set the USE_PRESENCE option when initializing your ConveyorServer:

1<?php
2
3include __DIR__ . '/vendor/autoload.php';
4
5use Conveyor\Constants;
6use Conveyor\ConveyorServer;
7
8(new ConveyorServer())
9    ->conveyorOptions([
10        Constants::USE_PRESENCE => true,
11    ])
12    ->port(8181)
13    ->start();

2. Associate a User ID on the Client

You must inform the server which user ID is connected. Below are two examples: Vanilla JS and using the Conveyor Client library.

2.1 Vanilla JS Example

1const ws = new WebSocket('ws://127.0.0.1:8181/?token=my-temporary-conveyor-token');
2
3ws.onopen = () => {
4  // Connect to a channel
5  ws.send(JSON.stringify({
6    action: 'channel-connect',
7    channel: 'my-channel',
8  }));
9  
10  // Send the user ID to the server
11  ws.send(JSON.stringify({
12    action: 'assoc-user-to-fd-action',
13    userId: 1,
14  }));
15
16  // (Optional) Broadcast a message to "my-channel"
17  ws.send(JSON.stringify({
18    action: 'broadcast-action',
19    data: 'My broadcast message.',
20  }));
21};

2.2 Conveyor Client Example

1const connect = () => {
2  const conveyor = new window.Conveyor({
3    protocol: 'ws',
4    uri: '127.0.0.1',
5    port: 8181,
6    channel: 'my-channel',
7    token: 'my-temporary-conveyor-token',
8    userId: 'unique-user-id', // <- This identifies this user's client
9    onMessage: (msg) => {
10      console.log('Received:', msg);
11    },
12    onReady: () => {
13      console.log('Connected');
14    },
15  });
16};
17
18document.addEventListener("DOMContentLoaded", connect);

3. Presence Event Messages

When a new connection joins a channel, each client in that channel receives a channel-connect message. Its data field will have an "event": "channel-presence", indicating a change in the active users on that channel. For example:

1{
2  "action": "channel-connect",
3  "data": "{json data here}"
4}

Where data might look like:

1{
2  "fd": 8,
3  "event": "channel-presence",
4  "channel": "private-notifications",
5  "fds": [4,8],
6  "userIds": {
7    "4": 255172010152673280,
8    "8": 453728974839278943
9  }
10}

• fd: The file descriptor (connection ID) that just joined.
• fds: All active connections in the channel.
• userIds: Mapped user IDs, showing which user is associated with each connection.

That’s it! Once presence is enabled and each client associates a user ID, you’ll automatically receive updates about who’s in any given channel.