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

​

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);