Realtime
Learn how realtime connections work in Xano and how you can incorporate them into your application.
Last updated
Learn how realtime connections work in Xano and how you can incorporate them into your application.
Last updated
Realtime can be defined as anything that enables your application to provide live updates inside of your application. Think of something like a chat window, where volume of interactions can be high, and it doesn't really make sense to constantly ping an API for new updates. Realtime enables an always-open connection, and in combination with our Javascript SDK or other frontend integration, can easily be enabled in your applications that use Xano as a backend.
Behind the scenes, Realtime connections are powered by a Websocket server to maintain connections. It can enable you to build dynamic and responsive functions for your website or application, such as a real-time chat, collaboration, or instant in-app notifications.
Realtime can also refer to database triggers, which is logic that can run immediately when something changes in a database table. For more information on triggers, see this section of our documentation.
When your client (user or application) connects to a Realtime channel in your backend, it will start listening for new messages. A channel is just a way to segregate messages into 'sections'; similar to having separate chat threads with different people, each thread would have its own channel.
A message can be anything you want, from plain text to complex JSON. To keep things easy to understand, the instructions below will be using plain text messages.
In this example, we have a channel for a 'Marvel Chat Room'. All of our users are connected to this chat room. Anytime someone sends a message, it will appear for every user connected. Functionally, this means that if Jill sends (or broadcasts) a new message, John and Jack will receive it, but Jill will also receive the message back; this makes it super simple to ensure that the view across all clients remains in sync.
Realtime allows you to use as many channels as you want. If we were to open a new channel, a 'DC Chat Room', and Jack joins both of them, he will be able to send and receive messages in both channels. John will not be able to interact with the DC chat room until he joins the channel; same with Jill and the Marvel chat room.
If you haven't done so already, you'll need to enable Realtime at the workspace level. From your workspace dashboard, open the menu in the top-right corner, choose Realtime Settings, change the dropdown to Yes, and then click Save.
If this is the first workspace to have Realtime enabled in your instance (even if you've had it enabled and then disabled it previously), Xano will need to provision the additional resources required for Realtime to function. This should only take a few minutes to complete, and you can check progress from the Realtime Settings panel.
After Realtime is enabled, you'll need to define some channel permissions. For a deep dive into how channel permissions work, see this section of our documentation.
We've made using Xano Realtime as easy as possible to build into your application by integrating it into our Xano SDK.
If you aren't familiar with Javascript, that's okay. We hope to have more direct integrations with your favorite frontends in the near future. Each code snippet is broken down into a special Code Explanation section to help you understand what's going on.
To get started, import the SDK to your project by...
Using our HTML import (best for beginners)
Using NPM
Next, you'll need to collect the following information:
An instance base URL, which you can find anywhere when logged into Xano.
The realtime connection hash, which is located in your Realtime Settings panel.
We need to initialize a new xanoClient, using the following Javascript.
If you are already initializing the SDK for other purposes, just add the realtimeConnectionHash
parameter. You do not need to specify instanceBaseUrl if you are providing an API group base URL.
We also need to define a channel for our messages to live in.
Now that you have initialized your Xano SDK and defined a channel, we can listening for new messages.
So far, we've enabled the Xano SDK, set up our Marvel channel, and implemented a function to listen for new messages. The last piece is to add a function to send new messages to the channel.
With that, we're ready to start building Realtime into our front-end! View and play with a completed example below.
Be aware that the demo code below assumes you have a channel called marvel-chat-room defined in your channel permissions. If you'd like to use a different channel name, find this line:
and update "marvel-chat-room" to your channel name.
Instructions:
Click here to open the demo in a new tab.
Fill in your API group base URL and Connection Hash.
Click 'Submit'.
To achieve the maximum effect, duplicate the tab and have a little chat with yourself!
To authenticate your users with channels that require authentication, you will use your xanoClient
as usual. The client will automatically authenticate if the realtimeAuthToken
setting is set.
After your xanoClient
is defined, perform an API request to your login or signup endpoint and store the returned auth token using the setRealtimeAuthToken command.
You can generate separate auth tokens when your users log in, sign up, or otherwise are ready to initiate a connection to Realtime.
Previously, this was accomplished with setAuthToken, and will continue to function as such until July 1, 2024. On that date, it will become required to use setRealtimeAuthToken instead to authenticate a realtime connection. If you don't need separate tokens, you can just supply the same auth token for both values.
The realtime connection has several different message types that can be sent, and you can modify your custom code to react differently to each message type.
connection_status
Informs the status of the connection to your Realtime server. This appears in your console log when initiating a connection to a channel.
error
An error has occurred connecting to or interacting with Realtime. Check your console log for more details.
event
An event is anything beyond a standard realtime message, and can be used to enable dynamic handling of different data being sent through Realtime
join
Sent when joining a channel
leave
Sent when leaving a channel
message
A new message has been received
presence_full
A full list of all clients connected to the channel
presence_update
Sent when a new client joins or leaves the channel
When setting up your Realtime channels, you have the option of storing message history as well.
Message history for your channels is backed by Redis cache, and it's important to consider how else you are using caching, if at all, when determining how much data to hold on to.
Message history can store up to 100 messages per channel, and can be returned to clients with the following:
Hungry for more Realtime? Check out the following sections of documentation for more information.
Check your browser's Javascript console for the following output: