Kandy-IO/kandy-link-js-sdk v5.0.0

Kandy kandy-link-js-sdk v5.0.0

on GitHub

5.0.0 - 2022-08-02

The v5.0 release of the Kandy JS SDK simplifies and improves how media tracks are handled for calls. It does not add any new features, but it fixes and clarifies the different scenarios around what/how tracks can be added or removed from a call. The majority of changes are internal to the SDK in how tracks are handled, but they affect how the SDK communicates with an application for this handling. The release also comes with recommendation changes on when an application should render/remove tracks to take into account the SDK changes.

As a major release, it includes a few breaking changes that application developers need to address. The 'Migration' section at the end of this release version includes information about the changes.

Added

• Added new call events: call:tracksAdded and call:tracksRemoved
  • These events are intended to replace the previous call:newTrack and call:trackEnded events.
  • These events notify when a Call operation, either performed locally or remotely, has added or removed tracks from a call. An event will be emitted once per operation (rather than per track affected) to inform of all local and/or remote tracks affected due to the operation.
  • These events signify that a track's media is available to be rendered (call:tracksAdded) or the track's media is no longer available to be rendered (call:tracksRemoved).
  • For more information, please see the API documentation for these events.
• Added new track event: media:trackEnded
  • This event signifies that a track was unexpectedly ended by an action outside the control of the SDK, but is still part of a Call.
  • This scenario was previously reported as part of call:trackEnded, but is now separate as its significance is very different.
  • For more information, please see the API documentation for this event.

Removed

• Removed the call events: call:newTrack and call:trackEnded
  • These events are replaced by the new call:tracksAdded and call:tracksRemoved events. These new events serve the same purposes, but are different enough where re-using the same events would be deceptive.
• Removed SDK functionality that would automatically remove an ended local track from a Call.
  • This is replaced by the new media:trackEnded event. Please see the 'Auto-Removal on Track Lost' section of this changelog for more information.

Changed

• Changed the significance for track events: media:sourceMuted and media:sourceUnmuted
  • These events now only signify that a track has unexpectedly lost (or regained) its media source for reasons outside the control of the SDK. Such as network issues for a remote track.
  • When a call operation causes a track to disconnect (or reconnect) from its media source, that will be handled by the new call:tracksRemoved and call:tracksAdded events instead.

Migration

call:newTrack --> call:tracksAdded

The functional differences between the previous call:newTrack and new call:tracksAdded events are very minor. The only change needed to handle the difference in parameters is that call:tracksAdded includes the list of all events affected, rather than a single track.

The conceptual differences between the call:newTrack and call:tracksAdded events are a little more significant. The call:tracksAdded event signifies that tracks are now part of the Call and their media can be rendered. Previously, the call:newTrack event signified a track was part of the Call but not necessarily that its media was available. Applications should now consider call:tracksAdded to be the time when a track can be rendered.

If an application has their business logic in a handleNewTrack function, then the event listener for call:newTrack can be adapted for call:tracksAdded as below. For more examples of the call:tracksAdded event being handled, please see our 'Voice and Video Calls' and 'Handling Media Tracks' tutorials.

// Example event listener for when a new track is added to a Call.
// Prior to v5.0 changes.
client.on('call:newTrack', function (params) {
  const track = client.media.getTrackById(params.trackId)
  // Call the application logic for how a new track should be handled.
  handleNewTrack(track, params.callId)
})

// Example event listener for when new tracks are added to a Call.
// For `call:tracksAdded`, an application should consider rendering the tracks
//    to be part of their application logic.
// Post v5.0 changes.
client.on('call:tracksAdded', function (params) {
  params.trackIds.forEach(trackId => {
    const track = client.media.getTrackById(trackId)
    // Call the application logic for how a new track should be handled.
    handleNewTrack(track, params.callId)
  })
})

call:trackEnded --> call:tracksRemoved

The differences between the call:trackEnded and call:tracksRemoved events are very similar as between the call:newTrack and call:tracksAdded events. The important difference to mention is a significance change: the call:tracksRemoved event signifies that tracks have been purposefully removed from a Call by an SDK operation. The media:sourceMuted and media:trackEnded events cover the unexpected scenarios. The tracks' media is no longer available to be rendered, and will not be available unless re-added to the Call with a call:tracksAdded event. Applications should not continue rendering a track after the call:tracksRemoved event.

If an application has their business logic in a handleTrackGone function, then the event listener for call:trackEnded can be adapted for call:tracksRemoved as below. For more examples of the call:tracksRemoved event being handled, please see our 'Voice and Video Calls' and 'Handling Media Tracks' tutorials.

// Example event listener for when a track has ended.
// Prior to v5.0 changes.
client.on('call:trackEnded', function (params) {
  const track = client.media.getTrackById(params.trackId)
  // Call the application logic for how a track ending should be handled.
  handleTrackGone(track, params.callId)
})

// Example event listener for when tracks are removed from a Call.
// For `call:tracksRemoved`, an application should unrender the tracks as part
//    of their application logic.
// Post v5.0 changes.
client.on('call:tracksRemoved', function (params) {
  params.trackIds.forEach(trackId => {
    const track = client.media.getTrackById(trackId)
    // Call the application logic for how a removed track should be handled.
    handleTrackGone(track, params.callId)
  })
})

media:sourceMuted & media:sourceUnmuted

The media:sourceMuted and media:sourceUnmuted events have had no functional changes. The significance of the media:sourceMuted event has changed to be focused on the scenario when a track unexpectedly loses access to its media source, for example a remote track will temporarily become "source muted" during network issues. Previously the event could be triggered by a Call operation, which will now be handled by the call:tracksRemoved event in the expected scenario.

The previous Kandy recommendation was to unrender a track when it becomes "source muted", since it could have been triggered by multiple causes. Now that the event is focused on media issues, unrendering the track is not a necessity and an application developer will need to decide how they want to convey a temporary media interruption to their end-user. If the tracks are left rendered during this time, an end-user would simply see/hear the remote media be "choppy" during the issues.

For more in-depth information about this scenario, please see the 'Handling Media Tracks' tutorial.

Auto-Removal on Track Lost

When a track unexpectedly ended, the SDK would previously remove that track from the Call automatically. This was done to cleanup the call, so that both sides of the call knew that the track was no longer available. This was not always desired
behaviour, though, and could interfere with how an application wanted to handle this scenario. To clarify this scenario, the new media:trackEnded has been added to explicitly signify a track loss (rather than it being grouped with the call:trackEnded event).

For an application to keep the same auto-removal behaviour when updating to the v5.0 SDK, they would need to handle this event by manually removing the track from the call, as shown below. This auto-removal behaviour was removed from the SDK to allow an application more flexibility in how this scenario should be handled, though. It could be an option to replace the track instead of outright removing it, for example. For more in-depth information about this scenario, and alternate options, please see the 'Handling Media Tracks' tutorial.

// Example event listener for the new `media:trackEnded` event, replicating the
//    previous "auto-removal" behaviour of the SDK.
// Post v5.0 changes.
client.on('media:trackEnded', function (params) {
  const { trackId, callId } = params
  const track = client.media.getTrackById(trackId)

  // Remove local tracks that end unexpectedly. This is the behaviour the SDK
  //    performed automatically prior to v5.0.
  if (track.isLocal) {
    client.call.removeMedia(callId, [trackId])
  }
})

Other Changes

The v5.0 release also includes changes to a few other parts of the SDK. These changes should not be noticeable to an application, but are worth mentioning for awareness. A number of features of the SDK have had their codebase renewed to better support the direction of the SDK going forward. This will translate to a better developer experience in the future.

The following features have been updated internally: Call History, ClickToCall, Contacts, Presence, Users, Voicemail. They do not require any application changes as part of v5.0, as the changes are backwards-compatible. As always, if you encounter an issue with a release change, please report the issue to us.