Looking for IceLink documentation? This product is discontinued and has been replaced by LiveSwitch. Please contact Sales to learn more and plan your migration today.

Migrate from IceLink to LiveSwitch Cloud

LiveSwitch improves the capabilities of IceLink by providing a server component for you that works out of the box and scales with your client-side needs. LiveSwitch comes with its own fully featured SFU and MCU modules, which allow you to scale up your video conferences to support more people than you could with IceLink. LiveSwitch also has built-in support for token-based authentication, application-specific roles and session management.

Cheat Sheet

IceLink → LiveSwitch Cloud
https://v4.websync.fm/websync.ashx https://cloud.liveswitch.io
Client.RequestUrl Client.GatewayUrl
Client.DomainName Client.ApplicationId
Client.DomainKey Client.SharedSecret
Client.Connect Client.Register
Client.Disconnect Client.Unregister
Client.Bind Client.Update
Client.Unbind Client.Update
Client.Subscribe Client.Join
Client.Unsubscribe Client.Leave
Client.Publish Channel.SendMessage
SubscribeArgs.OnReceive Channel.OnMessage
SubscribeArgs.OnClientSubscribe Channel.OnRemoteClientJoin
SubscribeArgs.OnUserJoin Channel.OnRemoteClientJoin
SubscribeArgs.OnClientUnsubscribe Channel.OnRemoteClientLeave
SubscribeArgs.OnUserLeave Channel.OnRemoteClientLeave
Publisher Web API

Getting Started

  1. First, create a LiveSwitch Cloud account if you don't have one.
  2. Create an Application using the LiveSwitch Cloud Console.
  3. Download the latest SDK and add it to your app.

You're ready to migrate.

Migrating involves converting code that references IceLink into code that references the LiveSwitch equivalents.

Not sure where to start? Just remove the IceLink SDK from your app and let your IDE tell you where to look.

Key Differences

There are some key differences to be aware of when migrating:

  1. Registering in LiveSwitch == connecting in IceLink.
  2. Unregistering in LiveSwitch == disconnecting in IceLink.
  3. Joining a channel in LiveSwitch == subscribing to a channel in IceLink.
  4. Leaving a channel in LiveSwitch == unsubscribing from a channel in IceLink.
  5. Updating a client in LiveSwitch == binding records to or unbinding records from a client in IceLink.
  6. Sending a message in LiveSwitch == publishing a message in IceLink.
  7. LiveSwitch uses a promise-based async/await model, as opposed to WebSync's callback model.
  8. Client requests are authorized by JSON web tokens.

Servers

LiveSwitch uses https://cloud.liveswitch.io as its signaling endpoint, also called the gateway URL. This is equivalent to the "request URL" in WebSync, which is https://v4.websync.fm/websync.ashx for WebSync Cloud.

Tokens

Tokens are used to authorize Register and Join requests. Register tokens authorize the initial connection, while Join tokens authorize a connected client to join a new channel. Register tokens can include a list of channels to join right away as part of the initial connection.

LiveSwitch tokens are simple JSON Web Tokens, an open, industry-standard method for representing claims securely between two parties.

Your LiveSwitch Cloud shared secret is used to sign tokens. It is very important to protect this shared secret. Generating tokens in a server-side API that can provide tokens to authorized users of your system is strongly recommended.

The simplest way to generate a token is to use the LiveSwitch SDK:

LiveSwitch

let applicationId = "my-app-id";
let userId = fm.liveswitch.Guid.newGuid().toString().replace(/-/g, '');
let deviceId = fm.liveswitch.Guid.newGuid().toString().replace(/-/g, '');
let userName = "John Doe";
let channelId = "123456";

let client = new fm.liveswitch.Client("https://cloud.liveswitch.io",
                                                    this.applicationId,
                                                    this.userId,
                                                    this.deviceId);

let claims = [new fm.liveswitch.ChannelClaim(channelId)];

let token = fm.liveswitch.Token.generateClientRegisterToken(
                    this.applicationId,
                    this.client.getUserId(),
                    this.client.getDeviceId(),
                    this.client.getId(),
                    null,
                    claims,
                    "--sharedSecret!--"
                );

Third-Party Library

You can also use a third-party library, like jsonwebtoken:

var sharedSecret = '...'; 

var registerToken = jwt.sign({
    type: 'register',
    applicationId: '...',
    userId: '...',
    deviceId: '...',
    channels: [{ // optional, any count
        id: '...'
    }],
    clientRoles: ['...'], // optional, any count
    region: '...' // optional
}, sharedSecret, {
    algorithm: 'HS256',
    expiresIn: 300 // seconds
});

var joinToken = jwt.sign({
    type: 'join',
    applicationId: '...',
    userId: '...',
    deviceId: '...',
    clientId: '...'
    channel: [{ // exactly 1 required
        id: '...'
    }]
}, sharedSecret, {
    algorithm: 'HS256',
    expiresIn: 300 // seconds
});

Migrating

Registering (Connecting)

Registering in LiveSwitch is equivalent to connecting in IceLink. Registering with the server requires a signed token for authorization.

Your LiveSwitch shared secret is equivalent to your WebSync domain key. This information is private for your servers only.

Your LiveSwitch Application ID is equivalent to your WebSync domain name. This information is public that you can include in your client apps.

Before (IceLink)

let client = new fm.websync.client('https://v4.websync.fm/websync.ashx');

this.client.connect({
  onSuccess: (args: any) => {
       console.log("connection success!");
  },
  onFailure: (args: any) => {
    console.log("Failed to connect.");
  },
});

After (LiveSwitch)

let applicationId = "my-app-id";
let sharedSecret = "---shared-secret---";
let channelId = "123456";

let client = new fm.liveswitch.Client("https://cloud.liveswitch.io", applicationId);
let claims = [new fm.liveswitch.ChannelClaim(channelId)];
let token = fm.liveswitch.Token.generateClientRegisterToken(
                    this.applicationId,
                    null,
                    null,
                    null,
                    null,
                    claims,
                    sharedSecret
                );

client.register(token).then((channels) => {
     fm.liveswitch.Log.info("Registered to Gateway!");
     // Run procedures after registering
     
     promise.resolve(null);
}, (ex) => {
     fm.liveswitch.Log.error("Failed to register with Gateway.");
     // Run procedures to handle exceptions
     
     promise.reject(ex);
});

Notice the null parameters when creating the Register token. These represent additional metadata (user ID, device ID, client roles) bound to the client and verified on the server.

You might also notice that an array of channels can be provided when registering. If provided, the server joins the client to these channels on registration. A Channel array is returned from the call to Register.

Unregistering (Disconnecting)

Unregistering in LiveSwitch is equivalent to disconnecting in IceLink.

Before (IceLink)

client.disconnect({
  onComplete: (args: any) => {
    console.log("Client disconnected");
  }
});

After (LiveSwitch)

client.unregister().then(() => {
  console.log("Unregistration successful!");
}).fail(() => {
  console.log("Failed to unregister client.");
});

Updating (Binding)

Updating in LiveSwitch is equivalent to binding and unbinding in IceLink.

LiveSwitch takes a simple approach to client metadata that allows it to scale better than WebSync. Each client has a UserAlias, a DeviceAlias, and a Tag property. You can change these values anytime by calling Update. Any of these three string properties can have any value, but the intention is that UserAlias represents the user's human-readable display name, DeviceAlias represents the device's human-readable display name, and Tag represents any additional metadata the app needs.

Before (IceLink)

this.client.bind({
  record: {
    userAlias: "Jane Doe",
    tag: "NewUser"
  },
  onFailure: (ex) => {
    console.log("Unable to bind.");
  },
  onSuccess: () => {
    console.log("Bind successful!");
  }
});

After (LiveSwitch)

let config = client.getConfig();
config.setUserAlias("Jane Doe");
config.setTag("NewUser");

client.update(config).then(() => {
  console.log("Update successful");
}, (exception) => {
  console.log("Update unsuccessful");
});

Joining

Joining in LiveSwitch is equivalent to joining a conference in IceLink. Joining a channel requires a signed token for authorization.

LiveSwitch introduces a new Channel type that is returned by the call to Join. Received messages are delivered to channel-level event handlers.

Before (IceLink)

var joinArgs = new fm.icelink.websync4.JoinConferenceArgs("/123456");
joinArgs.setOnSuccess((args) => {
    fm.icelink.Log.info("joined the conference");
});
 
joinArgs.setOnFailure((args) => {
    fm.icelink.Log.info("failed to join the conference");
});
 
joinArgs.setOnRemoteClient((remoteClient) => {
    // set up streams ...
    var connection = new fm.icelink.Connection([... stream array ...]);
    connection.setIceServers(...);
    return connection;
});
 
fm.icelink.websync4.ClientExtensions.joinConference(this.client, joinArgs);

After (LiveSwitch)

let applicationId = "my-app-id";
let sharedSecret = "---shared-secret---";
let channelId = "123456";

let client = new fm.liveswitch.Client("", applicationId);
let claims = [new fm.liveswitch.ChannelClaim(channelId)];
let token = fm.liveswitch.Token.generateClientRegisterToken(
                    this.applicationId,
                    null,
                    null,
                    null,
                    null,
                    claims,
                    sharedSecret
                );

client.join(channelId, token).then(function(channel) {
    console.log("successfully joined channel");
}).fail(function(ex) {
    console.log("failed to join channel");
});

Leaving

Leaving in LiveSwitch is equivalent to leaving a conference in IceLink.

Before (IceLink)

let channelId = "123456"
client.leaveConference({
    conferenceChannel: channelId,
 
    onSuccess: function(e) {
        console.log("left the conference");
    },
    onFailure: function(e) {
        console.log("failed to leave the conference");
    }
});

After (LiveSwitch)

let channelId = "123456"

client.leave(channelId).then(function(channel) {
    console.log("left the channel");
}).fail(function(ex) {
    console.log("failed to leave the channel");
});

Sending Messages (Publishing)

Sending messages in LiveSwitch is equivalent to publishing in IceLink.

LiveSwitch uses Channel objects for contextual sending and receiving of messages, as opposed to global Client methods in WebSync.

Before (IceLink)

let json = {
    userName: "John Doe",
    textMessage: "Hello!"
}
client.publish(new fm.websync.PublishArgs(channelId, JSON.stringify(json)));

After (LiveSwitch)

try {
    channel.sendMessage("Hello!");
} catch (exception) {
    console.log("Failed to send message");
}

Channel-level methods to send a message to a specific user, device, or client are also available in LiveSwitch.

Selective Forwarding Unit Connections (SFU)

LiveSwitch also introduces SFU connection units, which offer greater scalability than traditional P2P connections used in IceLink. Upstream and downstream connections are needed to create an SFU connection.

Upstream Connection

let localMedia = ...;
let channel = ...;

function openSfuUpstreamConnection(tag){
    let connection;
    let audioStream;
    let videoStream;


    if (this.localMedia.getAudioTrack() != null) {
        audioStream = new fm.liveswitch.AudioStream(this.localMedia);
    }

    if (this.localMedia.getVideoTrack() != null) {
        videoStream = new fm.liveswitch.VideoStream(this.localMedia);
    }

    connection = this.channel.createSfuUpstreamConnection(audioStream, videoStream);
    connection.addOnStateChange((connection) => {

        // --- Insert code here to track connection states --- //

    });

    
    connection.open();
    return connection;
}

Downstream connection

let channel = ...;

function openSfuDownstreamConnection(remoteConnectionInfo, tag){     
    let remoteMedia = new fm.liveswitch.RemoteMedia();

    let connection;
    let audioStream;
    let videoStream;

    if (remoteConnectionInfo.getHasAudio()) {
        audioStream = new fm.liveswitch.AudioStream(remoteMedia);
    }

    if (remoteConnectionInfo.getHasVideo()) {
        videoStream = new fm.liveswitch.VideoStream(remoteMedia);                
    }

    connection = this.channel.createSfuDownstreamConnection(remoteConnectionInfo, audioStream, videoStream);
    connection.addOnStateChange((connection) => {
        
        // --- Insert code here to track connection state --- //

    });

    connection.open();
    return connection;
}