Tokens
Tokens can be used to:
- restrict access to private Channels
- forcefully subscribe users to Channels
- authenticate and identify users connected to Channels
- send direct messages to users (instead of to entire Channels)
Tokens can be generated using our API, then you can pass them down to users so they can authenticate with Channels. A common implementation is to generate a Token per user on your backend, then store it with the user object in your database. You can then pass their token down to the user (via your API, for example) and it can be used with our Client-side SDK to authenticate with Channels.
Do I need to use Tokens?
Tokens are not necessary in every application. Some applications may choose to use Tokens for logged in users only, or even not at all - it really depends on your use case.
If you’re providing data that you want everyone to be able to see (without
signing into your app, for example) then it probably makes the most sense to use
an unprotected
channel, which can be subscribed to using our frontend SDKs
without using Tokens.
A good use-case for Tokens would be if you’re building something like a group messaging app, for example, and need to limit access to certain channels, such as private group chat channels, to specific users.
Server-side Examples
The examples below assume you have already set up the Hop server-side SDK.
Generating Tokens
You can generate Tokens manually (using our Console) or via our SDKs & API.
Here’s an example of generating tokens using the server-side SDK:
// Import your Hop SDK instance
import {hop} from '.';
const {id} = await hop.channels.tokens.create(); // id = leap_token_xxx - you can now store and pass this token to clients
Subscribing Tokens to Channels
When you subscribe a Token to a channel, it will be subscribed to that channel in realtime and it will be made available to any live connections using that Token.
In this example, let’s assume that we have a private channel with the ID game
.
// Import your Hop SDK instance
import {hop} from '.';
const channelId = 'game';
const userToken = 'leap_token_abc123';
await hop.channels.subscribeToken(channelId, userToken);
Sending Messages Directly to Tokens
// Import your Hop SDK instance
import {hop} from '.';
const userToken = 'leap_token_abc123';
const eventName = 'NOTIFICATION'; // this can be anything you want
await hop.channels.publishDirectMessage(userToken, eventName, {
title: 'Someone liked your post!',
description: 'Tap to view more.',
});
Determine if a Token is Online
You can use the isOnline
function to check if a Token is currently connected
to Channels.
// Import your Hop SDK instance
import {hop} from '.';
const userToken = 'leap_token_abc123';
const isOnline = await hop.channels.tokens.isOnline(userToken);
// isOnline: boolean
Client-side Examples
Using Tokens with Client-side SDKs
Implementing Tokens into your frontend app is super easy. Just pass it into
hop.init
in the token
key. For example:
import { hop } from "@onehop/client";
// hop.init should be called as early as possible in your application's lifecycle
// or, as soon as you have the leap token available
const client = hop.init({
projectId: "project_xxx": // replace with your project ID,
token: "leap_token_xxx" // the Token to authenticate with
});
// Optionally do something with the client
client.on('STATE_UPDATE', console.log);