Quick Start – BlackPine WebSockets Server

Here is a quick start example. You are going to learn how to connect all the pieces together and write your first WebSocket-based application with BlackPine server as a relying service.

Notice: Although, our server does not care if you use PHP or Python for server processing, we decided to prepare this example using PHP because we had to choose a language. You may easily implement your endpoint using any kind of server-side languages (Node.JS, Java, Python, etc.).

Notice: In order to run this example you are going to need a publicly available hosting with PHP support. Any kind of shared hosting is also suitable. You are also going to need Composer tool and BlackPine account (either free or paid).

1. Register to our free tier or buy a paid option. All further steps are the same for both options.

2. Wait for Welcome E-mail from us. You will find there two important things: BLACKPINE_SERVER_URL and a link to the Configuration Dashboard.

3. On your web server create blackpine directory and index.php file inside it. Then make it accessible under public domain. Let’s assume it would look like this: https://your-domain.com/blackpine/index.php It is crucial the URL to be publicly visible.

4. Download our supporting library. In order to do that please open command line tool, go to blackpine directory and run:

 composer require kainex/blackpine-server-php-library

This will create vendor directory containing our library that makes the integration a lot easier.

5. Edit index.php and add this code:

<?php
use Kainex\BlackPine\Server\{ServerApp, Endpoints\VanillaEndpoint, Model\Client, Response};

include_once "./vendor/autoload.php";

class MyApp extends ServerApp {

	// listen for client-connect event
	public function onClientConnect(Client $client, Response $response): void {
		$response->sendMessage($client->getId(), 'Hello World!'); // send 'Hello World!' text to the client
	}
	
}

$endpoint = new VanillaEndpoint();
$endpoint->handle(new MyApp());

Please note that this library requires PHP 8.3 or newer.

6. Return for a while to the welcome e-mail you received in step #2. Click on a Configuration Dashboard link and put https://your-domain.com/blackpine/index.php URL in Endpoint field and click Save. This way BlackPine server knows your endpoint URL. It may take some time before the update will take effect.

7. Now, it’s time to make some WebSockets connections. Go again to blackpine directory and create index.html file. Put the following code in it:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>BlackPine Hello World</title>
    </head>
    <body>
        <h1>Hello World!</h1>

        <button onclick="connect()">Connect</button>

        <script>
            const BLACKPINE_SERVER_URL = '-- put the correct URL here --';
            function connect() {
                let websocket = new WebSocket(BLACKPINE_SERVER_URL);

                websocket.addEventListener("message", (e) => {
                    alert(e.data);
                    websocket.close();
                    websocket = null;
                });
                websocket.addEventListener("error", (e) => alert('Connection error. Make sure you provided a valid BlackPine WebSockets server URI.'));
            }
        </script>
    </body>
</html>

Important: fill BLACKPINE_SERVER_URL constant value with the URL you received from us in the welcome e-mail. This is crucial.

8. Visit https://your-domain.com/blackpine/index.html and you should see Connect button. After clicking you should see ‘Hello World’ text. Here is how it works. The JS code connects to our WebSockets server. Then it notifies your endpoint https://your-domain.com/blackpine/index.php about various events such us: new client connection, new message of a client, client disconnection, etc. In the endpoint you have a chance to react to those events. In the example above we listen for ‘connection’ event and then immediately send a message to the client who has just connected. The message is then received in websocket.addEventListener(“message”, (e) => { … }) handler.

Anatomy of the process

Your server

BlackPine server

1. index.html: Client clicks “Connect” button and makes WebSocket connection to BlackPine server.

2. Accepts the connection. Performs initial checks.

4. index.php: The endpoint receives “client-connected” event.

3. Immediately notifies the endpoint on your server about the event which is “client-connect”.

5. index.php: Sends “Hello World” message to the client who has just connected.

6. Receives message request.

8. index.html: The client receives the message and displays it.

7. Sends message to the client.