Use Channels
Use channels to create connections and send or receive messages. Channels are textual identifiers that you can link between clients, connections, or messages. You don't need to "create" or "destroy" channels. A Client instance lets you join a channel by calling client.Join
, and then specifying the name of the channel and the token authorizing you to join that channel.
Channels are flexible. Use them in many ways: as individual channels, as notification subscriptions, or any other things your app might need.
Note
LiveSwitch channels have a maximum 24-hour connection duration, subject to your subscription plan. LiveSwitch channels automatically disconnect when they reach the maximum duration in your subscription plan.
Note
About the code examples on this page:
- For Unity, UWP, Xamarin Android, Xamarin iOS, and Xamarin macOS, use the C# code.
- For Java, use the Android code.
- For macOS, use the iOS code.
Join a New Channel
To join a channel, you must generate a token. The syntax for generating a token is similar to generating a token when registering with Gateway, but slightly different. Specify an array of FM.LiveSwitch.ChannelClaim
and call the GenerateClientJoinToken
method of the FM.LiveSwitch.Token
class to generate the token.
The following example shows how to generate a token to join a new channel on the client side. For your production environment, always generate an authorization token on the server side.
Note
Channel IDs are not case-sensitive. For example, my-awesome-channel-123
and My-Awesome-Channel-123
are the same channel.
var applicationId = "my-app";
var userId = "my-name";
var deviceId = "00000000-0000-0000-0000-000000000000";
var channelId = "99999999-9999-9999-9999-999999999999";
var client = new FM.LiveSwitch.Client(...);
string token = FM.LiveSwitch.Token.GenerateClientJoinToken(
applicationId,
client.UserId,
client.DeviceId,
client.Id,
new FM.LiveSwitch.ChannelClaim(channelId),
"--replaceThisWithYourOwnSharedSecret--"
);
See also: ChannelClaim
Once you have created a token, validate the token with the LiveSwitch Gateway. To do this, invoke the Join
method of your FM.LiveSwitch.Client
instance using the token and a channel ID. The channel ID that you specify must match the ID of the ChannelClaim
instance that you used to create the token. The Join
method returns a promise. You can inspect the promise to see whether the client has successfully joined the channel.
client.Join(channelId, token).Then((FM.LiveSwitch.Channel channel) => {
Console.WriteLine("successfully joined channel");
}).Fail((Exception ex) => {
Console.WriteLine("failed to join channel");
});
Send Messages
You can send text messages like chat, notifications about user events, syncing data, and so on. You can also include tags in the message with metadata information about the sender.
You can send text messages to everyone, specific users, or specific devices.
// To everyone
channel.addOnMessage((senderClientInfo, message) => {})
channel.sendMessage(text))
// To a specific user
channel.addOnUserMessage((senderClientInfo, message) => {})
channel.sendUserMessage(userId, text))
// To a specific device
channel.addOnDeviceMessage((senderClientInfo, message) => {})
channel.sendDeviceMessage(userId, deviceId, text))
Leave a Channel
A client might want to leave a channel when a video conference ends. To leave a channel, call the Leave
method of the FM.LiveSwitch.Client
instance and use the channelId
. The Leave
method returns a promise. You can inspect the promise to see whether the client has successfully left the channel.
client.Leave(channelId).Then((FM.LiveSwitch.Channel channel) => {
Console.WriteLine("left the channel");
}).Fail((Exception ex) => {
Console.WriteLine("failed to leave the channel");
});
If you leave a channel, the authorization token you used for this channel is now invalid. You must generate a new token to join the same channel.
In your app, you can join and leave a channel at any time.
Manage Presence
You can use RemoteClientInfo
of the Channel
object to manage presence. Once you have joined a channel, use the following mechanisms to access remote client data:
- Existing clients:
channel.getRemoteClientInfos
- Joining clients:
channel.addOnRemoteClientJoin
- Leaving clients:
channel.addOnRemoteClientLeave
You can use metadata, like the tag or user ID, on the RemoteClientInfo
object to identify a particular user.
// initial state
channel.getRemoteClientInfos().forEach(remoteClientInfo => {
console.info(
remoteClientInfo.getUserId() +
' is already in (' +
remoteClientInfo.getId() +
').'
)
})
// changes
channel.addOnRemoteClientJoin(remoteClientInfo => {
console.info(
remoteClientInfo.getUserId() + ' joined (' + remoteClientInfo.getId() + ').'
)
})
channel.addOnRemoteClientLeave(remoteClientInfo => {
console.info(
remoteClientInfo.getUserId() + ' left (' + remoteClientInfo.getId() + ').'
)
})
See also:
Kick Clients From a Channel
The Channel
object has a kickClient
method. In your app, you can kick clients out of a channel. To kick a client, your channel claim must have the CanKick
privilege.
The following code example shows how to:
- Create a channel claim and set the
CanKick
privilege to the channel claim. - Allow the client to kick other users in this channel.
var kickingChannelExampleClaim = new FM.LiveSwitch.ChannelClaim("KickChannel") {
CanKick = true
};
var claims = new ChannelClaim[] {
kickingChannelExampleClaim
};
See also:
To kick a client on the client-side, provide the ClientInfo
to Channel.KickClient
. The following code example shows how to kick a client when you have permissions:
Promise example to kick the client:
client.Register(token).Then(channels => {
// Register the client, returns an array of channels.
var channel = channels[0]; // We registered 1 channel, get that channel from array.
// remoteClientInfo is the ClientInfo object for the user you want to kick.
channel.KickClient(remoteClientInfo).Then(x => {
// Successful.
}).Fail(ex => {
FM.LiveSwitch.Log.Error("Failed to kick user.", ex);
});
});
Async/await example to kick the client:
var channels = await client.Register(token); // Register the client, returns an array of channels.
var channel = channels[0]; // We registered 1 channel, get that channel from array.
try {
// remoteClientInfo is the ClientInfo object for the user you want to kick.
await channel.KickClient(remoteClientInfo);
// Successful
} catch (Exception ex) {
FM.LiveSwitch.Log.Error("Failed to kick user.", ex);
}
See also:
To kick a client on the server-side, use the REST API.
The following cURL command shows how to kick a client from a channel:
curl --location -g --request DELETE 'https://liveswitch.io:9443/admin/api/v1/applications/{applicationId}/channels/{channelId}/users/{userId}' \
--header 'x-api-key: <your-api-key>' \
--header 'Accept: application/json' \
--header 'odata.metadata: minimal' \
--header 'odata.streaming: true' \
--data-raw ''