SocketBee Documentation

Appearance

Events ​

SocketBee uses a robust event-driven architecture to enable real-time communication between clients and servers. This guide will explain how events work in SocketBee, including key concepts such as channels, event types, and how to effectively utilize events in your application.

What Are Events? ​

Events in SocketBee are signals that indicate that something has happened. These can be actions such as a user joining a chat room, sending a message, or updating a status. Events are used to notify clients in real-time, allowing for dynamic and responsive applications.

Channels ​

Channels are virtual communication paths that group related events. Clients subscribe to channels to receive events broadcasted on them. Channels help to organize and control the flow of events in your application.

Example: Subscribing to a Public Channel ​

javascript
// Subscribe to a public channel named 'chat'
socketClient.subscribe('chat', () => {
    console.log('Subscribed to the chat channel');
});

Event Types ​

SocketBee categorizes events into different types based on their purpose and origin. Understanding these categories helps in managing the flow of information in your application.

Client Events ​

  • Client-Side Events: Emitted by the client and received by the server.
  • Server-Side Events: Emitted by the server and received by the client.
  • Bidirectional Events: Can be emitted and received by both client and server.

System Events ​

  • Connection Events: Triggered when a client connects or disconnects.
  • Error Events: Triggered when an error occurs.

Subscribing to Events ​

To receive events, clients must subscribe to the relevant channels. Subscribing to a channel involves joining that channel, allowing the client to receive events broadcasted on it.

Steps to Subscribe to a Channel ​

  1. Identify the Channel: Determine which channel you need to subscribe to based on the type of events you want to receive.
  2. Join the Channel: Use the appropriate method to join the channel. For private and presence channels, ensure authentication is handled.

Example: Subscribing to a Private Channel ​

javascript
// Subscribe to a private channel named 'private-chat'
socketClient.subscribe('private-chat', () => {
    console.log('Subscribed to the private-chat channel');
});

Listening to Events ​

Once subscribed to a channel, the client can listen for specific events. Listening involves defining event handlers that execute when the specified event occurs.

Key Points for Listening ​

  • Event Handlers: Functions or methods that are executed when an event is received.
  • Event Data: Information that is sent along with the event, which can be used by the event handler to perform specific actions.

Example: Listening for New Messages ​

javascript
// Listen for 'new-message' events
socketClient.listen('new-message', (data) => {
    console.log('Received new message:', data);
});

Broadcasting Events ​

Broadcasting is the process of sending events to all clients subscribed to a particular channel. This is typically done by the server, but clients can also broadcast events if client events are enabled and configured properly.

Broadcasting Workflow ​

  1. Create Event: Define the event name and data to be sent.
  2. Send Event: Emit the event on the desired channel.
  3. Handle Event: Ensure that clients have event handlers to process the received event data.

Example: Broadcasting a Message ​

javascript
// Broadcast a 'new-message' event with data
socketClient.broadcast({
    event: 'new-message',
    data: { text: 'Hello, world!' }
}, () => {
    console.log('Message broadcasted');
});

Whitelisting Origins ​

For security reasons, SocketBee requires that the origins (domains) from which your application will make requests are whitelisted. This prevents unauthorized domains from making requests to your SocketBee instance.

How to Whitelist Origins ​

  1. Log In: Access your SocketBee account.
  2. Navigate to App Settings: Go to your app's settings page.
  3. Add Origin: Under the "Whitelist Origins" section, add the domain of your application.
  4. Save Changes: Ensure the changes are saved and propagated.

Example: SocketBee App Settings.

Client Events ​

When sending events from clients (JavaScript), you do not need to provide a secret. Only the app ID and app key are required. However, the origin (domain) must be whitelisted in your SocketBee app settings, and options.client_events must be set to true. By default, client_events is set to false.

Example: Enabling Client Events ​

javascript
// Initialize SocketBeeClient with client_events set to true
const options = {
    client_events: true
};
const socketClient = new SocketBeeClient('your_app_id', 'your_app_key', options);

Best Practices ​

Use Appropriate Channels ​

  • Segregate Channels: Use different channels for different types of events to keep the data flow organized.
  • Private and Presence Channels: Use these for sensitive or user-specific data to enhance security and functionality.

Optimize Event Handlers ​

  • Efficient Handlers: Ensure that event handlers are optimized for performance to avoid delays in event processing.
  • Error Handling: Implement robust error handling within your event handlers to manage any issues gracefully.

Secure Your Application ​

  • Authentication: Use proper authentication mechanisms for private and presence channels.
  • Whitelisting: Regularly update your whitelisted origins to match your application's deployment.

By understanding how events work in SocketBee and following these guidelines, you can create efficient, real-time applications that are both secure and responsive.