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.

• CSharp
• Android
• iOS
• JavaScript

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.

• CSharp
• Android
• iOS
• JavaScript

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.

• JavaScript

// 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.

• CSharp
• Android
• iOS
• JavaScript

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.

• JavaScript

// 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:

• getRemoteClientInfos
• addOnRemoteClientJoin
• addOnRemoteClientLeave

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.

• CSharp
• Android
• iOS
• TypeScript

var kickingChannelExampleClaim = new FM.LiveSwitch.ChannelClaim("KickChannel") {
  CanKick = true
};

var claims = new ChannelClaim[] {
  kickingChannelExampleClaim
};

See also:

• CanKick

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:

• CSharp
• Android
• iOS
• TypeScript

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:

• KickClient

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 ''