SocketBee Documentation

Appearance

SocketBee Web Client ​

This guide will help you integrate SocketBeeClient into a web application using the provided minified script available on Unpkg.

We will cover the steps to include the script in your HTML file, initialize the client, and use its functionalities.

Including the Script ​

To use SocketBeeClient in your web application, you need to include the minified script from Unpkg. This script will provide access to the SocketBeeClient class, allowing you to create and manage WebSocket connections.

Why Include the Script? ​

Including the script from Unpkg does the following:

  • Provides the SocketBeeClient class, enabling you to interact with the SocketBee service.
  • Allows you to subscribe to channels, listen for events, and broadcast messages in real-time.
  • Simplifies the integration process by including all necessary dependencies in one script.

How to Include the Script ​

Add the following <script> tag to the <head> or the end of the <body> section of your HTML file. This will load the SocketBeeClient library from the Unpkg CDN:

html
<script src="https://www.unpkg.com/@socketbee/client@latest/dist/socketbee.min.js"></script>

By including this script, you gain access to the SocketBeeClient class, which you can then use to initialize your client and interact with your WebSocket server.

html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SocketBeeClient Example</title>
    <script src="https://www.unpkg.com/@socketbee/client@latest/dist/socketbee.min.js"></script>
</head>
<body>
    <h1>SocketBeeClient Web Example</h1>
    <div id="messages"></div>
    <input type="text" id="messageInput" placeholder="Type a message">
    <button onclick="sendMessage()">Send Message</button>

    <script>
        // Your JavaScript code will go here
    </script>
</body>
</html>

Initialization ​

Initialize the SocketBeeClient by creating an instance with your application ID, key, and optional configuration parameters.

html
<script>
    const app_id = 'your_app_id';
    const app_key = 'your_app_key';
    const options = {
        secret: 'your_app_secret', // Optional
        server: 'custom_server',   // Optional
        port: 443,                 // Optional
        region: 'your_region',     // Optional
        protocol: 'https'          // Optional
    };

    const socketClient = new SocketBeeClient(app_id, app_key, options);
</script>

Parameters ​

  • app_id (string): Your application ID.
  • app_key (string): Your application key.
  • options (object): An optional configuration object.
    • secret (string): Your application secret.
    • server (string): The server address (default is 'east-1.socket.socketbee.com').
    • port (number): The server port (default is 443).
    • region (string): The region of the server.
    • protocol (string): The protocol to use (default is 'https').

Methods ​

subscribe(channel, callback) ​

Subscribes to a specific channel and initializes the WebSocket connection.

Parameters ​

  • channel (string): The name of the channel to subscribe to.
  • callback (function): A callback function that is executed when the client joins the channel.

Usage ​

html
<script>
    socketClient.subscribe('my_channel', () => {
        console.log('Successfully joined the channel');
    });
</script>

listen(event, callback) ​

Listens for events on the subscribed channel.

Parameters ​

  • event (string): The name of the event to listen for.
  • callback (function): A callback function that is executed when the event is received.

Usage ​

html
<script>
    socketClient.listen('message', (data) => {
        console.log('Received message:', data);
        const messagesDiv = document.getElementById('messages');
        const messageElement = document.createElement('div');
        messageElement.textContent = data.text;
        messagesDiv.appendChild(messageElement);
    });
</script>

broadcast(event, callback) ​

Broadcasts an event to the subscribed channel.

Parameters ​

  • event (object): An object containing event details.
    • event.channel (string): The channel name (optional if already subscribed to a channel).
    • event.event (string): The event name.
    • event.data (any): The data to broadcast with the event.
  • callback (function): A callback function that is executed after broadcasting the event.

Usage ​

html
<script>
    function sendMessage() {
        const input = document.getElementById('messageInput');
        const message = input.value;
        if (message.trim() !== '') {
            socketClient.broadcast({
                event: 'new_message',
                data: { text: message }
            }, () => {
                console.log('Message broadcasted');
                input.value = '';
            });
        }
    }
</script>

Examples ​

Example 1: Basic Subscription and Listening ​

html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SocketBeeClient Example</title>
    <script src="https://www.unpkg.com/@socketbee/client@0.2.1/dist/socketbee.min.js"></script>
</head>
<body>
    <h1>SocketBeeClient Web Example</h1>
    <div id="messages"></div>
    <input type="text" id="messageInput" placeholder="Type a message">
    <button onclick="sendMessage()">Send Message</button>

    <script>
        const app_id = 'your_app_id';
        const app_key = 'your_app_key';
        const options = {
            secret: 'your_app_secret'
        };

        const socketClient = new SocketBeeClient(app_id, app_key, options);

        socketClient.subscribe('my_channel', () => {
            console.log('Successfully joined the channel');
        });

        socketClient.listen('new_message', (data) => {
            console.log('Received message:', data);
            const messagesDiv = document.getElementById('messages');
            const messageElement = document.createElement('div');
            messageElement.textContent = data.text;
            messagesDiv.appendChild(messageElement);
        });

        function sendMessage() {
            const input = document.getElementById('messageInput');
            const message = input.value;
            if (message.trim() !== '') {
                socketClient.broadcast({
                    event: 'new_message',
                    data: { text: message }
                }, () => {
                    console.log('Message broadcasted');
                    input.value = '';
                });
            }
        }
    </script>
</body>
</html>

Example 2: Using Custom Options ​

html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>SocketBeeClient Example</title>
    <script src="https://www.unpkg.com/@socketbee/client@0.2.1/dist/socketbee.min.js"></script>
</head>
<body>
    <h1>SocketBeeClient Web Example</h1>
    <div id="messages"></div>
    <input type="text" id="messageInput" placeholder="Type a message">
    <button onclick="sendMessage()">Send Message</button>

    <script>
        const app_id = 'your_app_id';
        const app_key = 'your_app_key';
        const options = {
            secret: 'your_app_secret',
            server: 'custom_server',
            port: 443,
            region: 'your_region',
            protocol: 'https'
        };

        const socketClient = new SocketBeeClient(app_id, app_key, options);

        socketClient.subscribe('my_channel', () => {
            console.log('Successfully joined the channel');
        });

        socketClient.listen('new_message', (data) => {
            console.log('Received message:', data);
            const messagesDiv = document.getElementById('messages');
            const messageElement = document.createElement('div');
            messageElement.textContent = data.text;
            messagesDiv.appendChild(messageElement);
        });

        function sendMessage() {
            const input = document.getElementById('messageInput');
            const message = input.value;
            if (message.trim() !== '') {
                socketClient.broadcast({
                    event: 'new_message',
                    data: { text: message }
                }, () => {
                    console.log('Message broadcasted');
                    input.value = '';
                });
            }
        }
    </script>
</body>
</html>