GuestClient
Summary
An application creates a GuestClient instance based on a given guest URL. After a successful connection, the other APIs on the client instance can be called. Event listeners are also exposed on the GuestClient instance.
Constructor
GuestClient
Syntax
GuestClient
-
config
Summary
Parameters:
-
config
ObjectObject literal containing configuration parameters
-
client_id
StringThe client ID you obtain from the Developer Portal. Identifies the client that is making the request.
-
[domain='circuitsandbox.net']
String optionalThe domain of the Circuit server to use. Defaults to circuitsandbox.net.
-
Item Index
Methods
- addEventListener
- addWhiteboardElement
- cancelMonitor
- clearWhiteboard
- clearWhiteboardBackground
- getActiveCall
- getAudioVideoStats
- getLastRtpStats
- getLocalAudioVideoStream
- getLocalScreenshareStream
- getRemoteStreams
- getWhiteboard
- joinConference
- leaveConference
- logout
- monitorSession
- mute
- muteParticipant
- removeWhiteboardElement
- setAudioVideoStream
- setMediaDevices
- setScreenshareStream
- setWhiteboardBackground
- toggleRemoteAudio
- toggleScreenShare
- toggleVideo
- toggleWhiteboardOverlay
- undoWhiteboard
- unmute
- validateToken
Properties
Events
Methods
addEventListener
Syntax
Summary
Register for Circuit events such as new a new message, incoming call, connection state change, etc.
Parameters:
-
type
StringEvent type such as
itemAdded
Returns:
callback See event definition on parameter(s) of callback function
Example:
// Register for connection state changes. E.g. connection going down and re-connecting
client.addEventListener('connectionStateChanged', function (evt) {
console.log('Received connectionStateChanged event. state: ', evt.state)
});
addWhiteboardElement
Syntax
Summary
Add a whiteboard element (e.g. circle, line, freehand) to the whiteboard.
Parameters:
-
xmlElement
StringSVG XML representation of the element. (Any JavaScript will be removed).
Returns:
A promise that is resolved when the drawing has been sent to the peers.
Example:
client.addWhiteboardElement(
. '
cancelMonitor
Syntax
cancelMonitor
()
Summary
Cancels an ongoing monitoring session
clearWhiteboard
Syntax
Summary
Clear a whiteboard.
Parameters:
Returns:
A promise that is resolved when the action has completed.
Example:
client.clearWhiteboard()
.then(() => console.log('Successfully cleared whiteboard'));
clearWhiteboardBackground
Syntax
Summary
Clear the background of the whiteboard.
Returns:
A promise without data.
Example:
client.clearWhiteboardBackground()
.then(() => console.log('Successfully cleared the background'));
getActiveCall
Syntax
Summary
Get local active call.
Returns:
A promise returning the local active call.
getAudioVideoStats
Syntax
Summary
The original WebRTC PeerConnection getStats API for the active, local Audio/Video PeerConnection, returning RTCStatsReport. Note that Chrome and Firefox return a different RTCStatsReport object. Check the browser. See https://www.chromestatus.com/feature/5665052275245056 and https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport. Calling this API more than once every 5 seconds will affect the performance. For a simpler, normalized API use the preferred client.getLastRtpStats API instead.
Returns:
A Promise containing RTCStatsReport object when successful
Example:
client.getAudioVideoStats()
.then(stats => stats.forEach(console.log))
.catch(console.error);
getLastRtpStats
Syntax
getLastRtpStats
()
RTCStatsReport
Summary
Get the RTP call statistics of the last stats collection interval (every 5 sec by default)
Returns:
An array of RTP stats, or for the new format a map of ID and RtpStats.
Example:
var stats = client.getLastRtpStats('8f365bf3-97ea-4d54-acc7-2c4801337521');
getLocalAudioVideoStream
Syntax
Summary
Get the local video stream (audio/video)
Returns:
A promise containing the MediaStream
Example:
client.getLocalAudioVideoStream()
.then(stream => console.log(stream));
getRemoteStreams
Syntax
Summary
Get the remote (receiving) media streams (audio, video and screenshare). For group calls there is one audio stream and 4 video streams. Not all streams may have audio/video tracks. For direct calls there is a single stream with audio and possibly video tracks.
Returns:
An array of MediaStream objects. Returns null
is call is not present.
Example:
var audioStream = client.getRemoteStreams().find(s => s.getAudioTracks().length > 0);
getWhiteboard
Syntax
Summary
Get the complete whiteboard drawing.
Returns:
A promise containing the whiteboard drawing.
Example:
client.getWhiteboard()
.then(board => console.log('Successfully retrieved the whiteboard'));
joinConference
Syntax
Summary
Join a conference as guest from the current device.
Parameters:
Returns:
A promise that is resolved when the call is joined.
Example:
client.joinConference('someToken', {firstName: 'John', lastName: 'Snow'}, {audio: true, video: false})
.then(() => console.log('Successfully joined the call'));
leaveConference
Syntax
Summary
Leave a conference call.
Returns:
A promise that is resolved when leaving the call is successful.
Example:
client.leaveConference('b3b97aa7-fe6c-48e1-9069-2e8d3b12f18a')
.then(call => console.log('Successfully left the call'));
logout
Syntax
Summary
Log this client instance out.
Returns:
A promise that is resolved after guest client is logged out.
Example:
client.logout();
monitorSession
Syntax
Summary
Monitors the guest conference with the given token until a session is started.
Parameters:
-
token
StringThe guest token to be validated
-
[interval]
Number optionalThe interval (in seconds) to poll the session status. Default is 5 seconds. Min. value is 5 seconds.
-
[duration]
Number optionalThe max. amount of time (in seconds) to wait for the session to start. Default is 1 minute. Max. value is 10 minutes.
Returns:
A promise that is resolved when the session has started.
Example:
client.monitorSession('someToken')
.then(() => console.log('Session has started'));
mute
Syntax
Summary
Mute an existing call.
Returns:
A promise that is resolved when the mute is complete.
Example:
client.mute()
.then(() => console.log('Successfully muted call'));
muteParticipant
Syntax
Summary
Mute a remote participant.
Parameters:
-
userId
StringUser ID of the participant to mute.
Returns:
A promise that is resolved when the participant has been muted.
Example:
client.muteParticipant('874c528c-1410-4362-b519-6e7d26a2edb2')
.then(() => console.log('Successfully muted participant'));
removeWhiteboardElement
Syntax
Summary
Remove a whiteboard element.
Parameters:
-
xmlId
StringSDK generated ID of the SVG elements.
Returns:
A promise that is resolved when the drawing has been removed.
Example:
client.addWhiteboardElement('someXmlId')
.then(() => console.log('Successfully removed whiteboarding element'));
setAudioVideoStream
Syntax
Summary
Set the media stream for audio/video to be transmitted in the active call.
Parameters:
-
stream
MediaStreamAudio/Video MediaStream to send.
-
[mediaType]
MediaType optionalMedia type for the call. If not set, audio/video is set based on tracks in stream.
Returns:
A promise that is resolved when the mediaStream has been set.
Example:
client.setAudioVideoStream('8f365bf3-97ea-4d54-acc7-2c4801337521', stream)
.then(() => console.log('Successfully set media stream'));
setMediaDevices
Syntax
Summary
Set the playback, recording, video and ringing devices to be used for calls. Can be called before or during a call. Use navigator.mediaDevices.enumerateDevices to get the available media devices. If multiple devices are set for a particular type (e.g. playback), then the first media device still available when starting the call is used.
Parameters:
-
devices
ObjectLiteral object containing the playback, recording, video and ringing device IDs.
-
[playback]
String | String[] optionalPlayback (audio output) media device ID, or array of IDs.
-
[recording]
String | String[] optionalRecording (audio input) media device ID, or array of IDs.
-
[video]
String | String[] optionalVideo (camera) media device ID, or array of IDs.
-
[ringing]
String | String[] optionalRinging media device ID, or array of IDs.
-
Returns:
A promise returning no content.
Example:
client.setMediaDevices({
recording: 'c2c9e42e18ad18d8dd16942ab653c029d81411fbbb2c6b8fedf7e0e36739099d',
video: ['617fb618597cef464e0bbe72c7978bc195435f9f04ac3d9d8961618d7d9fd07b', 'ed7e20a16115b672215db6479549abea11d41ba65de42b246d2575f678ac09be']
})
.then(() => console.log('New mic and camera device set'));
setWhiteboardBackground
Syntax
Summary
Set the background of the whiteboard.
Parameters:
-
file
FileFile object for background image.
Returns:
A promise without data.
Example:
client.setWhiteboardBackground(file)
.then(() => console.log('Successfully uploaded and set background'));
toggleRemoteAudio
Syntax
Summary
Toggle the incoming (remote) audio stream on an existing call.
Use callStatus
event and call.remoteAudioDisabled
to determine if remote audio is to be paused.
Returns:
A promise that is resolved when the toggle is complete.
Example:
client.toggleRemoteAudio()
.then(call => console.log(Remote audio state: ${call.remoteAudioDisabled}
));
// remoteAudio is the audio element
client.addEventListener('callStatus', evt => {
if (callId === evt.call.callId) {
if (remoteAudio.srcObject !== evt.call.remoteAudioStream) {
remoteAudio.srcObject = evt.call.remoteAudioStream;
}
if (evt.reason === 'remoteStreamUpdated') {
evt.call.remoteAudioDisabled ? remoteAudio.pause() : remoteAudio.play();
}
}
});
toggleVideo
Syntax
Summary
Toggle sending video on an existing call.
Returns:
A promise that is resolved when the toggle is complete.
Example:
client.toggleVideo('8f365bf3-97ea-4d54-acc7-2c4801337521')
.then(() => console.log('Successfully toggled'));
toggleWhiteboardOverlay
Syntax
Summary
Toggle the overlay of the whiteboard.
Returns:
A promise without data.
Example:
client.toggleWhiteboardOverlay()
.then(() => console.log('Successfully toggled the overlay'));
undoWhiteboard
Syntax
Summary
Undo recent changes to the whiteboard.
Parameters:
Returns:
A promise without data.
Example:
client.undoWhiteboard()
.then(() => console.log('Successfully undone steps'));
unmute
Syntax
Summary
Unmute an existing call.
Returns:
A promise that is resolved when the unmute is complete.
Example:
client.unmute()
.then(() => console.log('Successfully unmuted call'));
validateToken
Syntax
Summary
Validate the given guest token and verify if there is an ongoing session that can be joined.
Parameters:
-
token
StringThe guest token to be validated
Returns:
A promise that is resolved when the token is validated.
Example:
client.validateToken('someToken')
.then(data => console.log(data));
Properties
Events
callEnded
Syntax
callEnded
Summary
Fired when a call is terminated.
callNetworkQualityChanged (Unified plan enabled)
Syntax
callNetworkQualityChanged (Unified plan enabled)
Summary
Fired when call network quality changes.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
callId
StringID of the call
-
type
StringEvent name
-
data
ObjectCall quality object
-
userId
ObjectUser ID of local user -
audio
ObjectAudio quality object -
audio.qualityLevel
ObjectLow=1, Medium=2, High=3 -
audio.currentPlReceive
ObjectPacket Loss on receiving stream -
audio.currentPlSend
ObjectPacket Loss on sending stream -
audio.firstTimeLowQuality
Objecttrue if this is the first time with low quality on this call
-
-
-
event
ObjectObject literal containing the event properties
callRtpThresholdCleared
Syntax
callRtpThresholdCleared
Summary
Fired when call quality recovered after having reached the threshold.
callRtpThresholdReached
Syntax
callRtpThresholdReached
Summary
Fired when call quality falls below a predefined threshold.
callStatus
Syntax
callStatus
Summary
Fired when the call state, or any other call attribute of a local or remote call changes. Use the isRemote property to determine if the call is local or remote. A call is considered remote when a) the call is active on anohter device, or b) a group call is not joined yet.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
call
ObjectCall object
-
[participant]
Object optionalParticipant object for participant related reasons
-
[participants]
Object optionalParticipants object for participant related reasons
-
[recordingInfo]
Object optionaldata for
callRecording
reasons -
[activeSpeakers]
Object optionaldata for
activeSpeakerChanged
reason -
reason
StringReason event is triggered. Supported reasons are: callStateChanged, remoteStreamUpdated, localStreamEnded, callMuted, localUserMuted, localUserUnmuted, localUserSelfMuted, localUserSelfUnmuted, callLocked, callMoved, participantUpdated, participantAdded, participantJoined, participantRemoved, callRecording, droppedRemotely, sdpConnected, activeSpeakerChanged and whiteboardEnabled.
-
connectionStateChange
Syntax
connectionStateChange
Summary
Fired when the connection state changes.
sessionClosed
Syntax
sessionClosed
Summary
Fired when session has been forcefully closed by server.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
reason
SessionClosedReasonReason
-
whiteboardBackground
Syntax
whiteboardBackground
Summary
Whiteboard background set or cleared.
Event Payload:
-
event
ObjectObject literal containing the event properties
whiteboardCleared
Syntax
whiteboardCleared
Summary
Whiteboard cleared.
whiteboardConversionFailed
Syntax
whiteboardConversionFailed
Summary
Whiteboard conversion failed event.
whiteboardElement
Syntax
whiteboardElement
Summary
Whiteboard element added, removed or updated.
Event Payload:
-
event
ObjectObject literal containing the event properties
whiteboardEnabled
Syntax
whiteboardEnabled
Summary
Whiteboard enabled/disabled on a call.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
enabled
Booleantrue
if enabled,false
if disabled -
[whiteboard]
Whiteboard optionalThe whiteboard object (only when whiteboard becomes enabled)
-
whiteboardOverlayToggled
Syntax
whiteboardOverlayToggled
Summary
Whiteboard overlay toggled.
whiteboardSync
Syntax
whiteboardSync
Summary
Whiteboard sync event.
Event Payload:
-
event
ObjectObject literal containing the event properties
-
type
StringEvent name
-
[whiteboard]
Whiteboard optionalThe whiteboard object
-
[possibleUndoOperations]
Number optionalThe number of supported undo operations for the whiteboard.
-