- Channels can be of the
unprotected
type, which means that you don’t need to worry about handing out tokens to users on your frontend. This is useful if you want to display realtime data on a frontend application that doesn’t require user sign-in, for example. - You can send events directly to Tokens, instead of sending them to channels
- You can keep realtime, persisted “state” within a channel, which all clients are kept in sync with when connecting & when it’s updated. Read more ➜
- All capabilities can be mixed and matched with each other, allowing you to reap powerful benefits from individual channels without having to create hacky workarounds
Jump To
- Learn about Channel State
- Learn about Channel Tokens (authenticate users to Channels)
- Using Channels with React
- Creating Channels with the Hop SDK
- Updating Channel State using the Hop SDK
- Sending Messages to Channels using the Hop SDK
Concepts
Clients
The client (or “user”) is the entity that subscribes to Channels, using either the Hop SDK or via a custom Leap implementation. The client can be anything: a React app, a server-side application or an IoT device, for example.Tokens
For a client application to authenticate with protected (public & private) Channels, they will need to use token authentication. Tokens (leap_token_xxx
)
can be generated using the Hop API or SDK from your backend. Tokens can contain
metadata - for example, you could include the user ID this token is generated
for in. You are expected to securely hand this token to a client application,
which they can then use to authenticate with Channels through the Hop client
SDK.
Tokens can subscribe to many channels at once. They are permanent until deleted.
If you have a database of users, then you should create a token for each
individual user that needs to connect to Channels and store it in relation to
their user, then re-use that same token when they need to connect again in the
future.
You can connect and authenticate with Channels multiple times under the same
token.
Sessions
When a client SDK connects to the Channels socket, they are attached to a session individual to that token. Then, if a user connects multiple times under one token, they are connected to the same session. As a developer, you shouldn’t need to worry about this resource - just know that it’s used to keep a consistent and uninterrupted socket connection during unstable network conditions. Sessions automatically die once there have been no connected clients for a 30 second period. You can read more about them in the Leap documentation.Connections
Individual connections to the Channels socket are a separate resource, and while they’re attached to sessions, they get their own identifier which you can use to send messages to a single connection or “device”.Channel Subscriptions
A channel subscription refers to a client token being subscribed to a channel. Important: If you are just subscribing to unprotected channels on your frontend, then all channel subscriptions are ephemeral and only last the duration of the session / socket connection. There are 3 ways a token can be subscribed to a channel:- When creating the token, you can specify a list of “default channels” the token should be subcribed to
- Through the local client SDKs, the client can call the
subscribe
method with a channel ID. If the channel is private, then a webhook call will be required to succeed before the client is subscribed. - Through the server-side SDKs, you can call a method to subscribe one or multiple tokens to a channel
ephemeral
, which will delete the
subscription when the session dies.
Channels
By default, channels are direct, private, server->client realtime messaging rooms, however, channels are feature-rich and have be of multiple visibility types, and have multiple different Capabilities assigned to them. By default, channels are permanent until you delete them, however for some use cases, it might make more sense to give them theephemeral
capability, which makes them
automatically delete once all subscribers have disconnected.
Visibility Types
Channels can have one of 3 visibility types:- Private
- Public
- Unprotected