Channels are feature-rich and can be of multiple different visibility types and have multiple Capabilities enabled, allowing you to create anything from a realtime stock ticker to a fully feature-rich group messaging app.

Some nicities provided by Channels include:

  • 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

For most use cases, you’ll need a protected server-side application (e.g. an API) which can use the Hop SDK to generate Tokens and create Channels. You can then use the client-side SDKs to subscribe to channels.

​
Jump To

​
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

When client subscriptions are created, the realtime clients will instantly start receiving events from these channels.

All channel subscriptions are permanent across all sessions, and will last until a token is unsubscribed from a channel through the server-side API or local SDK. However, you can mark a subscription as ephemeral, which will delete the subscription when the session dies.

                                  ┌──────► channel_0
                                  │
                                  ├──────► channel_1
                                  │
User (Leap Token) ◄───► Session ◄─┼──────► channel_2
                                  │
                                  ├──────► channel_3
                                  │
                                  └──────► channel_4

​
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 the ephemeral capability, which makes them automatically delete once all subscribers have disconnected.

​
Visibility Types

Channels can have one of 3 visibility types:

  • Private
  • Public
  • Unprotected

Private channels allow you to individually grant tokens access to channels, either by calling a method from the server-side SDK or by responding to a webhook call when tokens try to subscribe, which you can set up on the Channels console page

Public channels allow anyone to join them, given they’re authenticated under your project and know the channel ID.

Unprotected channels allow anyone to join them, even if they’re not authenticated with a token, given they know the channel ID

​
State

State acts as a realtime data store attached to each channel. See Channel State

​
Messages

You can use the Hop API or SDK to easily send messages of any size to channels, which can then be handled by channel subscribers.

How to send Messages to Channels

Server Side Go Leap ClientChannel State