Web SDK

Getting Started

1. Install the SDK:

   • The easy way:

     <script src="https://unpkg.com/@realmq/web-sdk/dist/realmq.min.js"></script>

   • The flexible way:

     $ yarn add @realmq/web-sdk
     # or
     $ npm install @realmq/web-sdk

2. Initialize the SDK:

   const realmq = new RealMQ('<AUTH_TOKEN>');
   

3. Start implementing:

   // eg. load some data
   const channels = await realmq.channels.list();
   
   // or connect to the real-time API
   await realmq.rtm.connect();
   realmq.autoSubscribe();
   
   // listen for messages in some-channel
   realmq.rtm.on('some-channel/message', function channelMessageHandler(message) {
     console.warn('received new message in channel ', ${message.channel}, ':', message.data);
   });
   

Concepts

• Our SDK utilizes promises where possible.
• We provide convenient interfaces to work with resources retrieve, list, create, update and remove methods.
• realmq.rtm.* provides real-time functionality
• Each API resource has its own namespace.
  • realmq.channels.* - (Channel API)
  • realmq.subscriptions.* - (Subscription API)
  • realmq.tokens.* - (Token API)
  • realmq.users.* - (User API)
• There are two access groups (scopes). Every method has a description of what scopes are allowed to perform that action.
  • Admin Full management capabilities, use for implementing your real-time business logic
  • User Restricted access, use for logic on behalf of a single user/device/bot…

Initialization

Add the SDK to your html app:

<script src="https://unpkg.com/@realmq/web-sdk"></script>

Now you can initialize your real-time client.

const authToken = '<AUTH_TOKEN>';
const options = {
  host: 'realmq.your-domain.com'
};
const realmq = new RealMQ(authToken, options);

Channels

Create a channel

Admin

// create a simple channel
const channel1 = await realmq.channels.create();

// create a channel with a custom id
const channel2 = await realmq.channels.create({ id: 'awesome-channel' });

// create a channel with a message storage limit of 7 days
const channel3 = await realmq.channels.create({
  id: 'messages-within-the-last-week',
  features: {
    persistence: {
      enabled: true,
      duration: '7d',
    },
  },
});

Retrieve a channel

Admin User

const channel = await realmq.channels.retrieve('channel-id');

List all accessible channels

Admin User

Fetch a PaginatedList of Channels.

const channelList1 = await realmq.channels.list();
const channelList2 = await realmq.channels.list({ limit: 5, offset: 5 });

Update a channel

Admin

const channel = await realmq.channels.update('channel-id', [
  {
    op: 'replace',
    path: '/properties/memberCount',
    value: 47
  }
]);

Remove a channel

Admin

const channel = await realmq.channels.remove('channel-id');

Retrieving channel messages

Admin User

Fetch a PaginatedList of persisted messages within a Channel.

👉 Note: You have to enable channel persistence to retrieve messages from this resource.

const messages = await realmq.messages.list({
  channel: 'channel-id',
  offset: 10,
  limit: 10,
  from: '2023-08-01T11:03:42.58Z',
  to: '2023-08-01T11:03:42.58Z',
});

Subscriptions

Create a subscription

Admin

const subscription = await realmq.subscriptions.create({
  channelId: 'test-channel',
  userId: 'test-user',
  allowRead: true
});

Retrieve a subscription

Admin User

const subscription = await realmq.subscriptions.retrieve('subscription-id');

List all subscriptions

User

Fetch a PaginatedList of Subscriptions.

const subscriptionList1 = await realmq.subscriptions.list();
const subscriptionList2 = await realmq.subscriptions.list({ limit: 5, offset: 5 });

Update a subscription

Admin

const user = await realmq.subscriptions.update('subscription-id', [
  {
    op: 'replace',
    path: '/allowRead',
    value: true
  }
]);

Remove a subscription

Admin

const subscription = await realmq.subscriptions.remove('subscription-id');

Tokens

Create a token

Admin

Create a new auth token and passively create a new user if not existing yet. If you want to create an auth token for an existing user you have to pass its id as userId.

const user1 = await realmq.tokens.create();
const user2 = await realmq.users.create({ id: 'my-token-id', userId: 'test-user', scope: 'user' });

Retrieve a token

Admin User

Find an auth token by its id.

const user = await realmq.tokens.retrieve('token-id');

List all tokens

Admin User

Fetch a PaginatedList of Tokens of the current user, or system-wide if the request is performed as admin.

const userList1 = await realmq.tokens.list();
const userList2 = await realmq.tokens.list({ limit: 5, offset: 5 });

Update a token

Admin User

Update auth token via JSON-patch (RFC6902).

Patchable Fields

description

const user = await realmq.tokens.update('token-id', [
  {
    op: 'replace',
    path: '/description',
    value: 'Session on Chrome Linux'
  }
]);

Remove a token

Admin User

Delete the auth token and invalidate the session.

const user = await realmq.tokens.remove('token-id');

Users

Create a user

Admin

const user1 = await realmq.users.create();
const user2 = await realmq.users.create({ id: 'awesome-user' });

Retrieve a user

Admin

const user = await realmq.users.retrieve('user-id');

List all users

User

Fetch a PaginatedList of Users.

const userList1 = await realmq.users.list();
const userList2 = await realmq.users.list({ limit: 5, offset: 5 });

Update a user

Admin

const user = await realmq.user.update('user-id', [
  {
    op: 'replace',
    path: '/properties/avatar',
    value: 'https://api.adorable.io/avatars/64/avatar.png'
  }
]);

Remove a user

Admin

var user = await realmq.users.remove('user-id');

Real-time Gateway

Access our real-time API through realmq.rmt.*. Before you can send or receive messages, you need to establish a connection.

await realmq.rtm.connect();

👉 Info: There is also a realmq.rtm.disconnect() method.

Events

realmq.rtm emits the following events:

• connected
• reconnected
• disconnected
• message
• {channel}/message
• message-sent

Let’s register an event handler with realmq.rtm.on:

function onConnect() {}

realmq.rtm.on('connected', onConnect);

You can remove event handlers with realmq.rtm.off:

realmq.rtm.off('connected', onConnect);

Subscribe to a channel

After subscribing to a channel you will receive all messages published to that channel.

await realmq.rtm.subscribe({
  channel: 'test-channel'
});

👉 Note: Subscribe will fail if you do not have a read-enabled subscription on that channel.

Unsubscribe from a channel

After unsubscribing from a channel you will not receive any messages through that channel.

await realmq.rtm.unsubscribe({
  channel: 'test-channel'
});

Receive messages

Whenever a message hits the client, the SDK will emit message events.

• message will be emitted for every message.
• {channel}/message will be emitted for every message in a particular channel

realmq.rtm.on('message', function messageHandler(message) {});
realmq.rtm.on('some-channel/message', function channelMessageHandler(message) {});

The message object provides the following properties:

👉 Note: If your messages contain binary, you should access raw instead of data. Otherwise a JSON Parse exception might be raised.

Publish a message

We do not restrict you on what data of which format you publish.

You can send plain string messages:

await realmq.rtm.publish({ channel: 'test-channel', message: 'Welcome!' });

Or if you prefer binary:

const message = new Uint8Array([0x57, 0x65, 0x6c, 0x63, 0x6f, 0x6d, 0x65, 0x21]);
await realmq.rtm.publish({ channel: 'test-channel', message });

Or anything else:

const message = { '❤️': 'Welcome!' };
await realmq.rtm.publish({ channel: 'test-channel', message });

👉 Note: Non binary messages will be automatically JSON encoded.
👉 Note: Publish will fail if you do not have a write-enabled subscription on that channel.