Register a Client

To participate in a media conference, users need to communicate with each other. The LiveSwitch Gateway connects participants in a media session, controls which individuals they can communicate with, and restricts unauthorized access to a conference. To start a session, first register with the LiveSwitch Gateway. This section outlines the registration process and some of the core concepts of session management.

Note

About the code examples on this page:

For .NET MAUI and Unity use the C# code examples.

Grant Client Permissions

To grant a client the permissions to update the connection settings from the SDK, the client must be registered with a ChannelClaim that has the CanUpdate flag set to true. By default, the CanUpdate flag is set as false.

// ChannelClaims must have the "CanUpdate" flag set to true
var ChannelClaims = new[] { new ChannelClaim(ChannelId) { CanUpdate = true } };

// ChannelClaims must have the "CanUpdate" flag set to true
this.channel.getClaim().setCanUpdate(true);

// ChannelClaims must have the "CanUpdate" flag set to true
_channel?.claim.setCanUpdate(true);

// ChannelClaims must have the "CanUpdate" flag set to true
this.channel.getClaim().setCanUpdate(true);

// ChannelClaims must have the "CanUpdate" flag set to true
_channel?.claim.setCanUpdate(true);

Authorization Tokens

When you submit a request to register with the LiveSwitch Gateway, you must provide an authorization token. A token is a key encoded with the details of your authorization request. Each token is composed of these parts:

Application ID: An application's unique identifier. The LiveSwitch Server can accommodate multiple applications simultaneously, and this parameter is used to distinguish between them. If you only have a single application, you can hard-code this value.
User ID: A unique identifier, like a username, for a user who wants to register with the server.
Device ID: Generally, a random GUID that identifies which device the user is on. Used to distinguish sessions if a user is connected on multiple devices.
Client ID: A unique value generated when instantiating a Client instance. Generally only used if there are multiple clients running in a single application.
Roles: A designation that determines which sets of permissions a user has. In some applications, different users are given different sets of permissions. For example, a distance learning app might have a student role and a teacher role. You can omit roles if your app does not require them. If you do use roles, then the client must specify their roles in the .ctor, and the token roles are used to ensure that a client has permission to assume that set of roles. If a client attempts to assume a role that is not included by their registration token, then registration fails.
Channels: A channel is a unique identifier that describes an audio or video conference. Generally, for each video conference that you participate in, you have a unique channel associated with it.
Secret Key: A secret that is shared with the server and used to validate registration requests. You can hard-code this value, but you should not hard-code it in production. The secret key can be any arbitrary value.

Next, create one of these tokens and use it to register with the LiveSwitch Gateway.

Binding Hierarchy

For separating signalling concerns for different applications, channels, users, etc., LiveSwitch uses a combination of these IDs hierarchically: Application ID / Channel ID / User ID / Device ID / Client ID. This binding hierarchy uniquely binds the LiveSwitch signalling client, for a given device and a given user, to a channel for an application. This organization is flexible and versatile. You can have multiple channels for each application. In a channel, you can have multiple users. You could have a user in a channel, but using different devices. Whatever the use case, the binding hierarchy can meet the requirements for uniquely identifying your signalling concerns.

Register With the Gateway

Before you can start a media session, you must create a client and register with the LiveSwitch Gateway. In the first part of the registration process, you must create an authorization token. The server accepts or rejects the registration request based on the value of the token. The following code example shows you how to create a token for a simple registration request. The request has no roles, and only asks to join a single channel. The secret is also hard-coded for simplicity.

Note

Do not generate the token on the client side in production. We are doing so here for demo purposes only. See Creating an Auth Server for more information.

var applicationId = "Application";
var gatewayURl = "http://localhost:8080/sync";
var sharedSecret = "---sharedSecretHere---";
var userId = "10000001-0110-1001-0110-010101010101";
var deviceId = "11111111-1111-1111-1111-111111111111";
var channelId = "123456";

var client = new FM.LiveSwitch.Client(gatewayURL, applicationId, userId, deviceId, null, new [] {"role1", "role2"});

string token = FM.LiveSwitch.Token.GenerateClientRegisterToken(
    applicationId,
    client.UserId,
    client.DeviceId,
    client.Id,
    client.Roles,
    new[] { new FM.LiveSwitch.ChannelClaim(channelId) },
    sharedSecret
);

String applicationId = "my-app";
String userId = "my-name";
String deviceId = "00000000-0000-0000-0000-000000000000";
String channelId = "11111111-1111-1111-1111-111111111111";

fm.liveswitch.Client client = new fm.liveswitch.Client("http://localhost:8080/sync", applicationId, userId, deviceId, null, new String[] {"role1", "role2"});

String token = fm.liveswitch.Token.generateClientRegisterToken(
    applicationId,
    client.getUserId(),
    client.getDeviceId(),
    client.getId(),
    client.getRoles(),
    new fm.liveswitch.ChannelClaim[] { new fm.liveswitch.ChannelClaim(channelId) },
    "--replaceThisWithYourOwnSharedSecret--"
);

var applicationId = "my-app"
var userId = "my-name"
var deviceId = "00000000-0000-0000-0000-000000000000"
var channelId = "11111111-1111-1111-1111-111111111111"

var client = FMLiveSwitchClient(gatewayUrl: "http://localhost:8080/sync", applicationId: applicationId, userId: userId, deviceId: deviceId, clientId: nil, roles: ["role1", "role2"])

var token:String = FMLiveSwitchToken.generateClientRegisterToken(
    applicationId: applicationId,
    userId: client.userId(),
    deviceId: client.deviceId(),
    clientId: client.id(),
    clientRoles: client.roles(),
    channelClaims: [FMLiveSwitchChannelClaim(channelId: channelId)],
    sharedSecret: "--replaceThisWithYourOwnSharedSecret--"
)

var applicationId = "my-app";
var userId = "my-name";
var deviceId = "00000000-0000-0000-000000000000";
var channelId = "11111111-1111-1111-1111-111111111111";

var client = new fm.liveswitch.Client("http://localhost:8080/sync", applicationId, userId, deviceId, null, ["role1", "role2"]);

var token = fm.liveswitch.Token.generateClientRegisterToken(
    applicationId,
    client.getUserId(),
    client.getDeviceId(),
    client.getId(),
    client.getRoles(),
    [new fm.liveswitch.ChannelClaim(channelId)],
    "--replaceThisWithYourOwnSharedSecret--"
);

var applicationId = "my-app"
var userId = "my-name"
var deviceId = "00000000-0000-0000-0000-000000000000"
var channelId = "11111111-1111-1111-1111-111111111111"

var client = FMLiveSwitchClient(gatewayUrl: "http://localhost:8080/sync", applicationId: applicationId, userId: userId, deviceId: deviceId, clientId: nil, roles: ["role1", "role2"])

var token:String = FMLiveSwitchToken.generateClientRegisterToken(
    applicationId: applicationId,
    userId: client.userId(),
    deviceId: client.deviceId(),
    clientId: client.id(),
    clientRoles: client.roles(),
    channelClaims: [FMLiveSwitchChannelClaim(channelId: channelId)],
    sharedSecret: "--replaceThisWithYourOwnSharedSecret--"
)

After you have created a token, we must make a registration request. A registration request is made by invoking the Register method of the FM.LiveSwitch.Client instance that you created. This method returns a promise, which is resolved if registration is successful and is rejected if it is not successful. You should always validate the result of this promise before attempting to proceed with any further operations. If the registration is successful, then the promise returns a set of channels that it has registered the client to. These match the channels that you specified when you created your authorization token.

At this point, you would normally add a variety of event handlers to the FM.LiveSwitch.Channel instances. This is covered in the following sections:

For now, complete the registration, as shown in this code sample:

client.Register(token).Then((FM.LiveSwitch.Channel[] channels) =>
{
    FM.LiveSwitch.Log.Info("Client " + client.UserId + " has registered to channel" + channels[0].Id);         
}).Fail((Exception e) =>
{
    FM.LiveSwitch.Log.Error("Client " + client.UserId + " has failed to register");
});

client.register(token).then((fm.liveswitch.Channel[] channels) -> {
    System.out.println("connected to channel: " + channels[0].getId());
}).fail((Exception ex) -> {
    System.out.println("registration failed");  
});

client.register(withToken: theToken).then(resolveActionBlock: { [weak self] (obj: Any!) -> Void in
     self?._reRegisterBackoff = 200 // reset for next time
     self?.onClientRegistered(obj: obj)
}).fail(rejectActionBlock: { (e: NSException?) in
     FMLiveSwitchLog.debug(withMessage: "Failed to register client.",ex:e)
})

client.register(token).then(function(channels) {
    console.log("connected to channel: " + channels[0].getId());
}).fail(function(ex) {
    console.log("registration failed");
});

client.register(token: token).then(resolveAction: { (channels:[FMLiveSwitchChannel]) in
    print("connected to channel: " + channels[0].id())
}).fail(rejectAction: { (ex:NSException) in
    print("registration failed")
})

Note

This section assumes that you know which channels you want to join when you want to register. This is not always the case. Use Channel, describes how to join and leave channels after you have already registered with the LiveSwitch Gateway.

Unregister

Unregistering from the LiveSwitch Gateway before closing your app is best practice. The Gateway automatically unregisters clients that are inactive for a long period of time. However, unregistering manually ensures that resources are cleaned up in a timely fashion and that other clients are notified that a client has disconnected. To unregister a client, invoke the Unregister method of your Client instance. Like the Register method, Unregister also returns a promise, which you can inspect to see if unregistration is successful.

client.Unregister().Then((object result) =>
{
    FM.LiveSwitch.Log.Info("Client " + client.UserId + " has successfully unregistered");         
}).Fail((Exception e) =>
{
    FM.LiveSwitch.Log.Error("Client " + client.UserId + " has failed to unregister");
});

client.unregister().then((Object result) -> {
    System.out.println("unregistration succeeded");
}.fail((Exception ex) -> {
    System.out.println("unregistration failed");
});

client?.unregister()?.then(resolveActionBlock: { (obj: Any!) -> Void in
     self._unRegistering = false
}).then(resolveActionBlock: { (obj: Any!) -> Void in
     self.clientUnregistered?.invoke()
     self._dataChannelsConnected = false;
}).fail(rejectActionBlock: { (e: NSException?) in
     FMLiveSwitchLog.debug(withMessage: "Failed to unregister client.",ex:e)
})

client.unregister().then(function(result) {
    console.log("unregistration succeeded");
}).fail(function(ex) {
    console.log("unregistration failed");
});

client.unregister().then(resolveBlock: { (result:NSObject) in
    print("unregistration succeeded")
}).fail(rejectBlock: { (ex:NSException) in
    print("unregistration failed")
})

You are now able to connect your client-side applications with your LiveSwitch Gateway instance by generating a token and registering with the Gateway. This is the first step towards establishing a video conference. Remember that although we have only covered one way of joining channels, at registration, you can also join channels at any time afterwards. To learn more about joining channels, see Join a New Channel.