kandy-callMe-js-sdk

5.2.0

create

The SDK creation factory. Create an instance of the SDK by calling this factory with the desired configurations. The SDK instance will be referred as 'api' throughout the rest of the documentation content.

create(config: config): api
Parameters
config (config) The configuration object.
Returns
api: The SDK instance.
Example
// Instantiate the SDK.
import { create } from 'kandy'
const client = create({
    authentication: { ... },
    logs: { ... },
    ...
});
// Use the SDK's API.
client.on( ... );

config

The configuration object. This object defines what different configuration values you can use when instantiating the SDK using the create function.

config
Configurations By Feature
config.logs
config.authentication
config.call
config.connectivity
config.notifications

api

The 'api' is the type returned by the create function. It contains various top-level functions that pertain to SDK global instance as well as several nested namespaces that pertain to various features (e.g. call, contacts, presence, etc).

api
Types
BasicError
Functions
getVersion()
destroy()
getConfig()
updateConfig(newConfigValues)
on(type, listener)
off(type, listener)
subscribe(listener)
unsubscribe(listener)
getBrowserDetails()
getUserInfo()
Events
request:error

call

The 'call' namespace (within the 'api' type) is used to make audio and video calls to and from SIP users and PSTN phones.

Call functions are all part of the 'call' namespace.

call
Types
CallObject
MediaConstraint
MediaOffered
BandwidthControls
DSCPControls
RTCPeerConnectionConfig
IceServer
IceCollectionInfo
IceCollectionCheckFunction(iceCollectionInfo, iceTimeouts)
IceCollectionCheckResult
SdpHandlerInfo
SdpHandlerFunction(newSdp, info, originalSdp)
MediaObject
TrackObject
DevicesObject
DeviceInfo
CustomParameter
Functions
makeAnonymous(callee, credentials, callOptions)
hold(callId)
unhold(callId)
setCustomParameters(callId, customParameters)
sendCustomParameters(callId)
getAll()
getById(callId)
end(callId)
addMedia(callId, media, options = {})
removeMedia(callId, tracks, options = {})
startVideo(callId, videoOptions?, options?)
stopVideo(callId)
startScreenshare()
stopScreenshare()
sendDTMF(callId, tone, duration, intertoneGap)
getStats(callId, trackId?)
replaceTrack(callId, trackId, media)
getAvailableCodecs(kind)
setSdpHandlers(sdpHandlers)
states
mediaConnectionStates
restartMedia(callId)
setDefaultDevices()
changeInputDevices()
changeSpeaker()
Events
call:operation
call:start
call:receive
call:stateChange
call:newMedia
call:removedMedia
call:tracksAdded
call:tracksRemoved
call:statsReceived
call:trackReplaced
call:availableCodecs
call:mediaConnectionChange
call:mediaRestart

connection

The 'connection' namespace is used to connect and maintain connections between the SDK and one or more backend servers.

connection
Types
WSConnectionObject
Functions
getSocketState(platform)
enableConnectivityChecking(enable)
resetConnection()
Events
ws:change

logger

The SDK has an internal logging system for providing information about its behaviour. The SDK will generate logs, at different levels for different types of information, which are routed to a "Log Handler" for consumption. An application can provide their own Log Handler (see config.logs) to customize how the logs are handled, or allow the default Log Handler to print the logs to the console.

The SDK's default Log Handler is merely a thin wrapper around the browser's console API (ie. window.console). It receives the log generated by the SDK, called a "Log Entry", formats a human-readable message with it, then uses the console to log it at the appropriate level. This is important to be aware of, since your browser's console may affect how you see the SDK's default log messages. Since the default Log Handler uses the console's levels, the browser may filter which messages are shown depending on which levels it has configured. For a user that understands console log levels, this can be helpful for filtering the logs to only the relevant information. But it can equally be a hindrance by hiding the more detailed log messages (at the 'debug' level), since browser can have this level hidden by default. For this reason, we recommend providing a custom Log Handler to the SDK that is better suited for your application and its users.

logger
Types
LogEntry
LogHandler(LogEntry)
Functions
levels()

media

The 'media' namespace provides an interface for interacting with Media that the SDK has access to. Media is used in conjunction with the Calls feature to manipulate and render the Tracks sent and received from a Call.

Media and Track objects are not created directly, but are created as part of Call operations. Media and Tracks will either be marked as "local" or "remote" depending on whether their source is the local user's machine or a remote user's machine.

The Media feature also keeps track of media devices that the user's machine can access. Any media device (eg. USB headset) connected to the machine can be used as a source for media. Available devices can be found using the media.getDevices API.

media
Functions
getDevices()
getById(mediaId)
getTrackById(trackId)
initializeDevices(constraints?)
renderTracks(trackIds, cssSelector, options?)
removeTracks(trackIds, cssSelector)
muteTracks(trackIds)
unmuteTracks(trackIds)
Events
devices:change
devices:error
media:muted
media:unmuted
media:sourceMuted
media:sourceUnmuted
media:trackRendered
media:trackEnded

notification

The 'notification' namespace allows user to register/deregister for/from push notifications as well as enabling/disabling the processing of websocket notifications.

notification
Functions
process(notification, channel?)
registerApplePush(params)
registerAndroidPush(params)
unregisterApplePush(registrationInfo)
unregisterAndroidPush(registrationInfo)
enableWebsocket(enable)
Events
notifications:change
notifications:error

request

The 'request' namespace (within the 'api' type) is used to make network requests to the server.

request
Functions
fetch(resource, init)

sdpHandlers

A set of SdpHandlerFunctions for manipulating SDP information. These handlers are used to customize low-level call behaviour for very specific environments and/or scenarios.

Note that SDP handlers are exposed on the entry point of the SDK. They can be added during initialization of the SDK using the config.call.sdpHandlers configuration parameter. They can also be set after the SDK's creation by using the call.setSdpHandlers function.

sdpHandlers
Example
import { create, sdpHandlers } from 'kandy';
const codecRemover = sdpHandlers.createCodecRemover(['VP8', 'VP9'])
const client = create({
  call: {
    sdpHandlers: [ codecRemover, <Your-SDP-Handler-Function>, ...]
  }
})
// Through the Call API post-instantiation
client.call.setSdpHandlers([ codecRemover, <Your-SDP-Handler-Function>, ...])
Types
CodecSelector
Functions
createCodecRemover(codecs)