JavaScript SDK Reference

JavaScript SDK Reference

eventstypesvaluesparameters/argumentsfunctions/methodsproperties
?

Functions

onBistriConferenceReady = function(){…}

Function onBistriConferenceReady() is called when the JavaScript SDK has been loaded and is ready to use.
Return void.

Usage:

var onBistriConferenceReady = function(){
    // your code goes here
};

Objects

BistriConference (bc)

version

This property contains the JavaScript SDK version string

Usage:

console.log( BistriConference.version );
➥ "3.0.b-647efef"

init( conf )

Initialize JavaScript SDK.
Return void.

Usage:

BistriConference.init( {
    appId: "125...445",
    appKey: "edhh64...99v35",
    userName: "John Doe"
} );

Parameters:

  • conf: object, JavaScript SDK settings.
    Configuration keys:

    • appId: string, your application id (mandatory).
    • appKey: string, your application key (mandatory).
    • userId: string, user ID (optional). If no ID is passed, the server will generate its own “technical” ID
    • userName: string, user display name (optional). Default value is ""
    • chromeExtensionId: string, chrome extension id for screen-sharing feature (optional). To learn how to build your own extension please read: https://github.com/bistri/screensharing-extensions/tree/master/chrome-screensharing-extension
    • firefoxExtensionId: string, firefox extension id for screen-sharing feature (optional). To learn how to build your own extension please read: https://github.com/bistri/screensharing-extensions/tree/master/firefox-screensharing-extension
    • extAutoReload: boolean, automatically reload the page once the screen-sharing extension has been installed (optional).
      Default value is true
    • autoCloseOnExit: boolean, automatically close all connections when leaving/reloading the page (optional). Default value is true
    • debug: boolean, allow to log some information (optional). Default value is false

Note: your application ID and application Key could be retreived from your developer account
https://api.developers.bistri.com/admin/applications

Warning: we strongly recommend to set a referrer filter to prevent your application keys from being used by anybody. You can set it when editing your application parameters. Eg: my.domain.com* (don’t forget to add the wildcard suffix to match all your referrers)
Go to applications list

connect()

Open a new session on the server.
Return void.

Usage:

BistriConference.connect();

Event onConnected is triggered when the session has been successfully opened, otherwise event onError is triggered.

disconnect()

Close the session.
Return void.

Usage:

BistriConference.disconnect();

Event onDisconnected is triggered when the session has been closed.

joinRoom( roomName [, roomMaxCapacity] )

Join a conference room.
You can set the maximum number of participants in a room by using the roomMaxCapacity parameter. Only the first person joining the room can set the limitation. By default the maximum number of participants is limited to 256.
Return void.

Note:
The maximum number of participants must be adjusted  according to the kind of calls that will be done. We strongly recommend to limit audio/video calls to 4 participants, since most of actual CPUs can’t encode/decode more than 4 video streams at a time. Pure audio conference can be limited to 10 participants. Data-channels are not concerned by those limitations.

Usage:

BistriConference.joinRoom( "my_conference_room", 4 );

Parameters:

  • roomName: string, room to join.
  • roomMaxCapacity: integer, max room participants (optional).

If the room doesn’t exist, it will be created.

Event onJoinedRoom is triggered when user has successfully joined the room, other members already present into the room will receive an event onPeerJoinedRoom.
Otherwise event onJoinRoomError is triggered

quitRoom( roomName )

Quit conference room.
Return void.

Usage:

BistriConference.quitRoom( "my_conference_room" );

Parameters:

  • roomName: string, room to quit

Event onQuittedRoom is triggered when the user has leaved the room, other room members will receive event onPeerQuittedRoom.
Otherwise an event onQuitRoomError is triggered.

call( remoteUserId, roomName, options )

Start a call with a remote user.
Return void.

Usage:

BistriConference.call( "rfpWEk", "my_conference_room" );

Parameters:

  • remoteUserId: string, ID of the remote user to call.
  • roomName: string, room where the call take place.
  • options: object, optional parameters.
    Available options:

    • stream: MediaStream, stream to use for the call.
    • sendonly: boolean, if true remote streams will be not accepted.
    • audio-codec: string, preferred audio codec: Opus/48000, ISAC/32000, ISAC/16000 (Chrome only).
    • audio-bitrate: integer, audio bitrate kb/s (Chrome only).
    • video-bitrate: integer, video bitrate kb/s (Chrome only).

If the user hasn’t joined the room previously, he will be automatically added to the room and event onJoinedRoom will be triggered

At this point there are 2 cases:

1 – The user you are calling is already present in the room:
the call is processed and event onStreamAdded is triggered shortly after, when the remote audio/video stream is received.

2 – The user you are calling is not present in the room yet, but he is connected to the service:
event onIncomingRequest is triggered on the remote user side to invite him to join the room for a call.

Note: to know if a remote user is connected to the service you can use the getPresence() method and check if he is online or not.

openDataChannel( remoteUserId, label, roomName )

Open a data channel with the remote user.
Return void.

Usage:

BistriConference.openDataChannel( "rfpWEk", "chat_channel", "my_conference_room" );

Parameters:

  • remoteUserId: string, ID of the remote user to call.
  • label: string, data channel label.
  • roomName: string, room where the call take place.

If the user hasn’t joined the room previously, he will be automatically added to the room and event onJoinedRoom will be triggered

As for the call() method there are 2 cases:

1 – The user you are calling is already present in the room:
the request is processed and event onDataChannelCreated is triggered on the local user side and event onDataChannelRequested is triggered on the remote user side.

2 – The user you are calling is not present in the room yet, but he is connected to the service:
event onIncomingRequest is triggered on the remote user side to invite him to join the room for a call.

Note: to know if a remote user is connected to the service you can use the getPresence() method and check if he is online or not.

endCall( remoteUserId, roomName )

End a call with a peer.
Return void.

Usage:

BistriConference.endCall( "rfpWEk", "my_conference_room" );

Parameters:

  • remoteUserId: string, ID of the remote user.
  • roomName: string, room where the call take place.

Event onStreamClosed is triggered on the remote side when the call ended.

endCalls( roomName )

End all calls for a given room.
Return void.

Usage:

BistriConference.endCalls( "my_conference_room" );

Parameters:

  • roomName: string, room where the call take place.

Event onStreamClosed is triggered on the remote side when the call ended.

getMediaSources( callback )

List available media sources.
Return an array of sources if browser is Google Chrome, either return boolean false.

Usage:

BistriConference.getMediaSources( function( sources ){ console.log( "Sources:", sources ) } );
➥ Sources: [ { facing: "", id: "96d64b0...", kind: "audio", label: "Default" }, { ... }, { ... } ]

Parameters:

  • callback: function called when sources have been listed.

startStream( mediaConstraints, callback )

Start local stream.
Return void
Because of security purpose, HTTPS is required by the browser to access to the local stream !.

Usage:

BistriConference.startStream( "320x240:12", function( stream ){
    // display stream into the page
    BistriConference.attachStream( stream, document.body );
} );

Parameters:

  • mediaConstraints: object or string, media constraints.
    Possible values are:

    • { video: true, audio: true }: classical constraints object.
    • pure-audio: audio only stream.
    • {video-width}x{video-height}[:{frame-rate}]: user defined resolution, frame rate is optional.
    • webcam-hd: “1280×720” webcam stream.
    • webcam-sd: “640×480” webcam stream.
    • screen-sharing: screen sharing. This feature is only available for Chrome and Firefox (desktop).
      Both Chrome and Firefox require an add-on to use the screen-sharing
      Chrome extension sources are available on our GitHub.
    • Firefox extension sources are available on our GitHub.

  • callback: function called when the local stream start to flow.

stopStream( localStream, callback )

Stop local stream.
Return void.

Usage:

BistriConference.stopStream( stream, function(){
    // remove stream from the page
    BistriConference.detachStream( stream );
} );

Parameters:

  • localStream: MediaStream, stream to stop.
  • callback: function called when the local stream has been stopped.

When no callback has been passed to the method to handle the stopped stream, the event onStreamClosed is triggered on the local side.

attachStream( stream, node, options )

bind a stream object to a DOM node to display it.
Return audio/video html node.

Usage:

BistriConference.attachStream( stream, document.body, {
    autoplay: true,
    fullscreen: true,
    controls: true,
    mirror: true
} );

Parameters:

  • stream: MediaStream, stream to attach to the DOM node.
  • node: object, DOM node in which the media will be inserted.
  • options: object, display options, optional
    Available options:

    • autoplay: boolean
      Start to play automatically the stream once inserted into the page.
      Default value is set to true.
    • fullscreen: boolean
      Allow the user to switch to fullscreen mode by clicking on the video.
      Default value is set to false.
    • controls: boolean
      Display video controls.
      Default value is set to false.
    • mirror: boolean
      flip video on vertical axis (like in a mirror).
      Default value is set to false.

detachStream( stream )

remove a stream from the DOM tree.
Return void.

Usage:

BistriConference.detachStream( stream );

Parameters:

  • stream: MediaStream, stream to remove.

getPresence( remoteUserId )

Get the presence status of a remote user.
Return void.

Usage:

BistriConference.getPresence( 'rfpWEk' );

Parameters:

  • remoteUserId: string, remote user ID.

Event onPresence is triggered when the presence is received.

setPresence( presenceStatus )

Set local user presence status.
Return void.

Usage:

BistriConference.setPresence( 'away' );

Parameters:

  • status: string, local user status.
    Possible values are:

    • online
    • away
    • busy
    • offline

muteMicrophone( status )

Mute the microphone.
Return void.

Usage:

BistriConference.muteMicrophone( true );

Parameters:

  • status: boolean, microphone status.

muteSound( stream, status )

Mute audio track of a given stream. Sound is muted locally.
Return void.

Usage:

BistriConference.muteSound( stream, true );

Parameters:

  • stream: MediaStream, stream to mute.
  • status: boolean, sound status.

muteAllSounds( status )

Mute all audio tracks of remote streams. Sound is muted locally.
Return void.

Usage:

BistriConference.muteAllSounds( true );

Parameters:

  • status: boolean, sound status.

muteVideo( stream, status )

Mute video track of a given stream. Video is muted on local and remotes sides.
Return void.

Usage:

BistriConference.muteVideo( stream, true );

Parameters:

  • stream: MediaStream, stream to mute.
  • status: boolean, video status.

Event onStreamMuteChange is triggered on local and remote sides when the video track is un/muted.

isMicrophoneMuted()

Return true if the microphone is muted.
Return boolean.

Usage:

console.log( "microphone muted: ", BistriConference.isMicrophoneMuted() );
➥ microphone muted: true

isAllSoundsMuted()

Return true if all remote audio streams tracks are muted.
Return boolean.

Usage:

console.log( "all sounds muted: ", BistriConference.isAllSoundsMuted() );
➥ all sounds muted: true

isVideoMuted()

Return true if the local video track is muted.
Return boolean.

Usage:

console.log( "local video muted: ", BistriConference.isVideoMuted() );
➥ all sounds muted: true

getLocalStreams()

Return an array of local media stream objects.

Usage:

console.log( BistriConference.getLocalStreams() );
➥ [ MediaStream, MediaStream, ... ]

getRemoteStreams( roomName )

Return an object containing pairs of remote user ID / remote MediaStream objects.

Usage:

console.log( BistriConference.getRemoteStreams() );
➥ { 'St9d9JU7': MediaStream, 'xHoYffVm': MediaStream, ... }

Parameters:

  • roomName: string, room name. Use this optional parameter to get the streams of a particular room.

getDataChannels( roomName )

Return an object containing pairs of remote user ID / remote Data Channels objects.

Usage:

console.log( BistriConference.getDataChannels( roomName ) );
➥ { 'St9d9JU7': { 'chat': DataChannel, 'filetransfert': DataChannel }, ... }

Parameters:

  • roomName: string, room name.

getRoomMembers( roomName )

Return an array of users object

Usage:

console.log( BistriConference.getRoomMembers( roomName ) );
➥ [ { id: 'St9d9JU7', name: 'Jane Smith' }, ... ]

Parameters:

  • roomName: string, room name.

addStream( remoteUserId, roomName, stream )

Add a new stream to an existing call. Note: Firefox doesn’t support this method yet !
Return void.

Usage:

            BistriConference.addStream( 'St9d9JU7', 'my_conference_room', stream );

Parameters:

  • remoteUserId: string, ID of the remote user.
  • roomName: string, room where the call take place.
  • stream: MediaStream, stream to add.

Event onStreamAdded is triggered on the remote user side once the stream has been added.

removeStream( remoteUserId, roomName, stream )

Remove a stream from an existing call. Note: Firefox doesn’t support this method yet !
Return void.

Usage:

BistriConference.removeStream( 'St9d9JU7', 'my_conference_room', stream );

Parameters:

  • remoteUserId: string, ID of the remote user.
  • roomName: string, room where the call take place.
  • stream: MediaStream, stream to remove.

Event onStreamClosed is triggered on the remote user side once the stream has been removed.

monitorAudioActivity( stream, callback )

Monitor stream audio level (VU meter). Audio level is measured on a 0 to 100 scale.
Note: because of a Chrome bug it is not possible to monitor remote streams.
Return void.

Usage:

BistriConference.monitorAudioActivity( stream, function( audioLevel ){
    console.log( 'level:', audioLevel );
} );
➥ level: 34
➥ level: 67

Parameters:

  • stream: MediaStream, stream to monitor.
  • callback: function, executed when an audio activity is detected.

isConnected()

Return a boolean according to the api server connection state

Usage:

console.log( "is connected to api server:", BistriConference.isConnected() );
➥ is connected to api server: true

isCompatible()

Return a boolean according to the WebRTC compatibility

Usage:

console.log( "is browser compatible:", BistriConference.isCompatible() );
➥ is browser compatible: true

isScreenSharingCompatible()

Return a boolean according to the screen-sharing compatibility

Usage:

console.log( "is screen-sharing compatible:", BistriConference.isScreenSharingCompatible() );
➥ is screen-sharing compatible: true

getWebRTCPluginURL()

WebRTC plugin download URL.
Return string

Usage:

console.log( "plugin URL:", BistriConference.getWebRTCPluginURL() );
➥ plugin URL: https://temasys.atlassian.net/wiki/display/TWPP/WebRTC+Plugins

isWebRTCPluginUsed()

Return true if the browser use the WebRTC plugin (Safari, Internet Explorer).
Return boolean

Usage:

console.log( "is WebRTC plugin used:", BistriConference.isWebRTCPluginUsed() );
➥ is WebRTC plugin used: true

isWebRTCPluginAvailable()

Return true if the Temasys plugin is available for the current platform/browser.
Return boolean

Usage:

console.log( "is WebRTC plugin available:", BistriConference.isWebRTCPluginAvailable() );
➥ is WebRTC plugin available: true

signaling

bind( eventName, callback )

Register a handler for a given event related to the signaling. Many handlers could be registered for a same event.
Return a handler object.

Usage:

BistriConference.signaling.bind( 'onConnected', function( sessionData ){
    ...
} );

Parameters:

  • eventName: string, event name.
  • callback: function executed when the related event is triggered.

Events:

onError, onConnected, onJoinedRoom,
onJoinRoomError, onQuittedRoom, onQuitRoomError,
onPeerJoinedRoom, onPeerQuittedRoom, onDisconnected,
onIncomingRequest, onPresence, onStreamMuteChange,
onClientUpdateRequired.

unbind( handler )

Unregister a handler for a given event related to the signaling.
Return void.

Usage:

var handler = BistriConference.signaling.bind( 'onConnected', function(){...} );
...
BistriConference.signaling.unbind( handler );

Parameters:

  • handler: object returned by bind() method.

streams

bind( eventName, callback )

Register a handler for a given event related to the streams. Many handlers could be registered for a same event.
Return a handler object.

Usage:

BistriConference.streams.bind( 'onStreamAdded', function( stream, id ){
    ...
} );

Parameters:

  • eventName: string, event name.
  • callback: function executed when the related event is triggered.

Events:

onStreamAdded, onStreamClosed, onStreamRemoved, onStreamError, onStreamStatsUpdated.

unbind( handler )

Unregister a handler for a given event related to the streams.
Return void.

Usage:

var handler = BistriConference.streams.bind( 'onStreamAdded', function(){...} );
...
BistriConference.streams.unbind( handler );

Parameters:

  • handler: object returned by bind() method.

channels

bind( eventName, callback )

Register a handler for a given event related to data channels. Many handlers could be registered for a same event.
Return a handler object.

Usage:

BistriConference.channels.bind( 'onDataChannelRequested', function( dataChannel ){
    ...
} );

Parameters:

  • eventName: string, event name.
  • callback: function executed when the related event is triggered.

Events:

onDataChannelCreated, onDataChannelRequested.

unbind( handler )

Unregister a handler for a given event related to data channels.
Return void.

Usage:

var handler = BistriConference.channels.bind( 'onDataChannelRequested', function(){...} );
...
BistriConference.channels.unbind( handler );

Parameters:

  • handler: object returned by bind() method.

Data Channel

label

Data channel label

Usage:

console.log( "data channel label:", dataChannel.label );
➥ data channel label: chat_channel

send( message )

Send a message through the data channel.
Return void.

Usage:

    dataChannel.send( "my message" );

Parameters:

  • message: string, message to send.

onMessage callback is invoked on the remote user side when the message is received.

close()

Close the data channel.
Return void.

Usage:

            dataChannel.close();

onClosed callback is invoked on the remote user side when the data channel is closed.

onOpen = function(){…}

Callback invoked when the data channel is open and ready to emit.
Return void.

Usage:

dataChannel.onOpen = function(){
    console.log( "Data Channel open" );
};

onMessage = function( message ){…}

Callback invoked when a message is received on the data channel.
Return void.

Usage:

dataChannel.onMessage = function( event ){
    console.log( "New Message:", event.data );
};

Arguments:

  • event: object, message received.

onClose = function(){…}

Callback invoked when the data channel is closed.
Return void.

Usage:

dataChannel.onClose = function(){
    console.log( "Data Channel closed" );
};

onError = function( error ){…}

Callback invoked when an occurred.
Return void.

Usage:

dataChannel.onError = function( error ){
    console.log( "Data Channel error:", error );
};

Arguments:

  • error: string, error message.

Events

Signaling Events

onError( error )

Events triggered when a global error occurred.

Arguments:

  • error: JSON, error object.
    Object detail:

    {
        "code": "xxx", // error code
        "text": "..." // error reason
    }

Error codes:

  • 000: api access not authorized
  • 301: no room found
  • 401: failed to save user data

onConnected( session )

Event triggered when user is connected to signalling server.
Event linked to: connect()

Arguments:

  • session: JSON, session data.
    Object detail:

    {
        "clientVersion": "3.0.b-647efef", // last JavaScript SDK version available
        "id": "rfpWEk" // user session id
    }

onJoinedRoom( room )

Event triggered when user has successfully joined the room.
Event linked to: joinRoom(), call(), openDataChannel()

Arguments:

  • room: JSON, room data.
    Object detail:

    {
    	"room": "aUpS45g7J0w" // room id
    	"members":[ // array of remote users already connected to room
    		{
    			id: "aVlxUi", // remote user id
    			name: "Jane Doe" // remote user display name
    		},
    		...
    	],
    }

onJoinRoomError( error )

Event triggered when user fails to join the room.
Event linked to: joinRoom(), call(), openDataChannel()

Arguments:

  • error: JSON, error data.
    Object detail:

    {
    	"code": "xxx", // error code
    	"text": "..." // error reason
    }

Error codes:

  • 101: user is already present in room
  • 102: the room reached its max capacity
  • 103: the room doesn\’t exists
  • 104: user is not present in room
  • 105: forbidden chars in room name
  • 106: maximum simultaneous joined rooms reached

onQuittedRoom( room )

Event triggered when user has successfully quitted the room.
Event linked to: quitRoom()

Arguments:

  • room: JSON, room data.
    Object detail:

    {
    	"room": "aUpS45g7J0w" // room id
    }

onQuitRoomError( error )

Event triggered when user fails to quit the room.
Event linked to: quitRoom()

Arguments:

  • error: JSON, error data.
    Object detail:

    {
    	"code": "xxx", // error code
    	"text": "..." // error reason
    }

Error codes:

  • 201: no room found

onPeerJoinedRoom( peer )

Event triggered when a remote user (peer) has joined a room the local user is member of.
Event linked to: joinRoom(), call(), openDataChannel()

Arguments:

  • peer: JSON, peer data.
    Object detail:

    {
    	"room":"aUpS45g7J0w", // room id
    	"name":"John Doe", // peer display name
    	"pid":"rfpWEk" // peer id
    }

onPeerQuittedRoom( peer )

Event triggered when a remote user (peer) has quitted the room the local user is member of.
Event linked to: quitRoom()

Arguments:

  • peer: JSON, peer data.
    Object detail:

    {
    	"room":"aUpS45g7J0w", // room id
    	"pid":"rfpWEk" // peer id
    }

onDisconnected()

Event triggered when user is disconnected from the service.
Event linked to: disconnect()

onIncomingRequest( request )

Event triggered when a contact invite the user to join a room.
Event linked to: call()

Arguments:

  • request: JSON, request data.
    Object detail:

    {
    	"room":"aUpS45g7J0w", // room id
    	"pid":"rfpWEk", // peer id
            "event": "call" // request: "call" for a call request, "call-stop": to end a call, "datachannel": for a datachannel request
    }

onPresence( presence )

Event triggered when a contact presence status is received.
Event linked to: getPresence()

Arguments:

  • presence: JSON, presence data.
    Object detail:

    {
    	id: "rfpWEk", // contact id
    	presence: "online" // contact presence status
    }

onClientUpdateRequired( version )

Event triggered when the user un/mute the video stream.
Event linked to: connect()

Arguments:

  • version: JSON, version data.
    Object detail:

    {
    	clientVersion: "3.0.b-647efef", // new client version
    }

onExtensionInstallStarted()

Event triggered when the Chrome Screen-Sharing extension installation has started.

onExtensionInstalled()

Event triggered when the Chrome Screen-Sharing extension installation has succeed.

onExtensionInstallFailed()

Event triggered when the Chrome Screen-Sharing extension installation has failed.

Streams Events

onStreamAdded( stream, id )

Event triggered when a new remote stream is received
Event linked to: call(), addStream()

Arguments:

  • stream: MediaStream, remote stream.
  • id: string, remote user id.

onStreamClosed( stream, id )

Event triggered when a remote stream is stopped
Event linked to: endCall(), endCalls(), removeStream()

Arguments:

  • stream: MediaStream, remote stream.
  • id: string, remote user id.

onStreamRemoved( stream, id )

Event triggered when a remote stream is removed (after a call renegociation)
Event linked to: removeStream()

Arguments:

  • stream: MediaStream, remote stream.
  • id: string, remote user id.

onStreamError( error )

Event triggered when an error occurred while retrieving the local stream
Event linked to: startStream()

Arguments:

  • error: Object, error information.

onStreamMuteChange( streamStatus, pid )

Event triggered on local and remote side when a user un/mute his video stream.
Event linked to: muteVideo()

Arguments:

  • streamStatus: Boolean, video stream status, true if mute.
  • pid: String, peer id.

onStreamStatsUpdated( stats, id )

Event triggered when stream statistics have been updated.
Note: chrome only feature

Arguments:

  • stats: JSON, stats data.
    Object detail:

    {
    	"local":{ ... }, // sent stream stats
    	"remote":{ ... } // received stream stats
    }
  • id: string, remote user id.

Data Channels Events

onDataChannelCreated( dataChannel, id )

Event triggered when a data channel has been created on the local user side.
Event linked to: openDataChannel()

Arguments:

  • dataChannel: object, Data Channel. More about Data Channel
  • id: string, remote user id.

onDataChannelRequested( dataChannel, id )

Event triggered when a data channel has been created on the remote user side.
Event linked to: openDataChannel()

Arguments:

  • dataChannel: object, Data Channel. More about Data Channel
  • id: string, remote user id.