npm i --save @withkoji/dispatch|
Warning
|
This package is deprecated and is included only for backwards compatibility. For new templates, use withkoji-koji-core.html. |
The @withkoji/dispatch package enables you to implement real-time functionality in your Koji template. For example, chats, multi-player games, and polls.
You can use dispatch on the frontend to enable real-time updates and communication between connected clients. You can also use it transactionally on the backend to send secure messages to specific clients that have been identified with a short-lived token.
Install the package in your Koji project.
|
Note
|
You must also install the withkoji-vcc-package.html package. |
npm i --save @withkoji/dispatchInstantiates Dispatch.
project – Object, dispatch configuration for your Koji project.
Contains the following properties:
projectId – String, unique identifier for your Koji project.
You can use the withkoji-vcc-package.html package to obtain this value programmatically.
options – (Optional on frontend) Object, configuration options for the dispatch instance.
Contains the following properties:
shardName – (Optional) String, name of the specific shard to use.
If this key is not present, the user will be placed into a shard automatically.
maxConnectionsPerShard– (Optional) Number, total users to allow on a shard before it is "full."
When a shard is full, new users are added to a new shard unless a different shard is explicitly set.
projectToken – (Backend only) String, secret key for the Koji.
authorization – (Backend only, Optional) String, temporary token that identifies the client, so the server and other connected clients can send it secure messages.
If the token is not included, you can use identify to identify the client after it is connected.
import Dispatch from '@withkoji/dispatch';
// Frontend
const dispatch = new Dispatch({
projectId: instantRemixing.get(['metadata', 'projectId']),
});
// Backend
const dispatch = new Dispatch({
projectId: res.locals.KOJI_PROJECT_ID || process.env.KOJI_PROJECT_ID,
options: {
projectToken: res.locals.KOJI_PROJECT_TOKEN || process.env.KOJI_PROJECT_TOKEN,
},
});String, temporary token that identifies the connected client, so the server and other connected clients can send it secure messages.
To get a token, use getToken in the @withkoji/auth package.
String, ID of the currently connected client.
Object, contains IDs of currently connected clients as keys and an object of their user data.
{
"0dc15e36-81b4-442b-be4d-bf590ee73c2a": {
username: "test1",
lastPing: 1600218622595
},
"1fe2eb80-57e3-435f-9314-faa74853c34a": {
username: "test2",
lastPing: 1600218623097
}
}Number, the latency of the last message in milliseconds.
String, name of the shard the client is currently connected to.
Object, the user information of the currently connected client. This can be modified using .setUserInfo.
(Async) Connects the dispatch client to an open shard.
dispatch.connect();(Async) Disconnects the dispatch client from the active connection.
dispatch.disconnect();Emits the named event to the specified recipients or all clients.
eventName – String, name of the event.
payload – Any, data to send with event.
recipients – (Optional) Array of Strings, list of clients to receive the event.
If this parameter is not included, the event is sent to all clients on the current shard.
dispatch.emitEvent('myEvent', myDataPayload);Identifies a connected client, which enables the server and other connected clients to send it secure messages.
authToken – String, temporary token for the connected client.
To get a token, use getToken in the @withkoji/auth package.
token = await auth.getToken(
['username', 'push_notifications'],
);
dispatch.identify(token);Gets information about the shard the client is currently connected to.
(Async) ShardInfo, Object describing the shard the client is currently connected to with shard name and number of connected clients.
dispatch.info.then((info) => {
currentInfo = info;
});Sets a listener for a specific event, and runs the handler when the event is dispatched over the shard.
For Koji custom events, see DISPATCH_EVENT.
To send your own events, see emitEvent.
eventName – String, name of the event to subscribe to.
handler – Function, the handler to run when the event is fired.
Receives the following property as input:
payload – Any, the data payload sent from the fired event.
dispatch.on('myEvent', myHandlerFunction);
// or with a custom payload
dispatch.on('myOtherEvent', (payload) => {
// payload sent from the emitted event available here
});Removes listeners from the specified event.
eventName – String, name of the event to unsubscribe from.
dispatch.removeEventListener('myEvent');Sets the current user’s information (see .userInfo) and broadcasts the update in the currently connected shard.
userInfo – Any, the data for user information to set.
dispatch.setUserInfo({username:"myUsername"});Constant holding special event keys for Koji Dispatch. To subscribe to these events see on.
DISPATCH_EVENT.CONNECTED – Fired when the current client has successfully connected to a shard.
Passes the following properties in its payload object:
clientID - String, Unique ID of the user on the shard that’s been connected to
shardName - String, Name of the shard that’s been connected to
DISPATCH_EVENT.CONNECTED_CLIENTS_CHANGED - Fired when the list of clients currently connected to the shard changes.
Passes the following property in its payload object:
connectedClients - Object, Mapping of connected client’s IDs and their respective userInfo.
import Dispatch, { DISPATCH_EVENT } from '@withkoji/dispatch';
const dispatch = new Dispatch({
projectId: instantRemixing.get(['metadata', 'projectId'])
});
dispatch.connect();
dispatch.on(DISPATCH_EVENT.CONNECTED, ({ clientId, shardName }) => {
// client has connected to shard
});
dispatch.on(DISPATCH_EVENT.CONNECTED_CLIENTS_CHANGED, ({ connectedClients }) => {
// connected clients has changed
});Koji dispatch includes utility functions to help you build realtime multiplayer games and applications.
import { Utils } from '@withkoji/dispatch';Checks whether a string contains profanity. This method can be useful for checking usernames or chat content.
string – String, text to check.
Boolean, indicates whether the specified string contains profanity.
Utils.profanity('check this string');Replaces profanity in a string with asterisks.
string – String, text to sanitize.
String, text with profanities replaced with asterisks.
Utils.filterProfanity('sanitize this string');Core package replacement modules: Dispatch (backend), Dispatch (frontend)