Quickstart Guide

Welcome to Relaybox, we're excited you're here!

This quickstart guide will run through some of the basic requirements to connect and begin using the service. If you haven't already, please follow these steps to create a free account and add your first application.

Install the Client SDK Library

In order to connect to RelayBox you first need to install the client library SDK. The library is made available via the NPM registry.

npm install @relaybox/client

Connecting an Application

Once the installation is complete, you'll be able to access the service by initializing a new RelayBox instance.

import { RelayBox } from '@relaybox/client';

const relayBox = new RelayBox({
  apiKey: xxxx.xxxx.xxxxxxxx // Replace with your api key
});

await relayBox.connect();

Create and Join a Room

Rooms are logical groups of connections that enable communication via events. To create a room, call the join() method passing the name of the room as an argument.

const myFirstRoom = await relayBox.join('myFirstRoom');

If the room does not already exist, joining will create it.

Subscribing to Events

Events are data packets transmitted to other connections listening for them (subscribers). To subscribe to an event, provide an event name and a handler function to process data as it arrives.

await myFirstRoom.subscribe('message', (data) => {
  console.log(data);
});

Above, a subscription to the "message" event has been registered with a corresponsing callback function to handle the data. In our case, we will simply log the data in the console.

Publishing an Event

To publish an event, call the publish() method, providing an event name and the data to transmit. Since we're already subscribed, let's publish a "message" event...

const response = await myFirstRoom.publish('message', { hello: 'universe' });

Putting It All Together

Putting that all together, we can see the overall structure of the code.

import { RelayBox } from '@relaybox/client';

const relayBox = new RelayBox({
  apiKey: xxxx.xxxx.xxxxxxxx // Replace with your api key
});

await relayBox.connect();

const myFirstRoom = await relayBox.join('myFirstRoom');

await myFirstRoom.subscribe('message', (data) => {
  console.log(data);
});

const response = await myFirstRoom.publish('message', { hello: 'universe' });

Here, we've established a connection and joined a room. We've subscribed to an event and published an event. All connections in the room subscribed to either this specific event or to all room events will receive this data in real-time.

Note: Always be cautious, never expose production API keys!

This guide uses an API key directly in the client-side code. While this approach is possible and the quickest way to connect, it should be used with caution. The recommended, secure approach is to generate auth tokens using a designated endpoint.

Where now?

This guide covers the basics of connecting to Relaybox services and using the client library SDK. For more detailed information on the libraries available, please refer to the technical documentation: