Documentation Class: UserAgent

new UserAgent(options)

Create an User Agent

Parameters:

Name	Type	Description
`options`	UserAgentOptions	all user connection options

Fires:

Returns:

Created object

Type: UserAgent

Example

Create an UserAgent

var user1 = new apiRTC.UserAgent({
  uri: 'apirtc:user2@apirtc.com'
});

Extends

Observable

Methods

<static> getAvailableEvents()

Returns available events for this class

Returns:

Type: Array.<string>

createStream(options)

A promise for creating a stream object

Parameters:

Name	Type	Description
`options`	CreateStreamOptions

Returns:

Created Stream in a promise

Type: Promise.<Stream>

createStreamFromMediaStream(mediaStream)

A promise for creating a stream object from a MediaStream

Parameters:

Name	Type	Description
`mediaStream`	MediaStream

Returns:

Created Stream in a promise

Type: Promise.<Stream>

enableActiveSpeakerDetecting(enabled, options)

Enables detecting the active speaker.

Parameters:

Name Type Description

enabled

boolean

If true, detecting the active speaker is enabled, otherwise detecting the active speaker is disabled.

options

object

Options.

Properties

Name	Type	Description
`threshold`	number	User defined threshold. Integer between 0 and 1

enableCallStatsMonitoring(enabled, options)

Enables call statistics monitoring.

Parameters:

Name Type Description

enabled

boolean

If true, call statistics monitoring is enabled, otherwise call statistics monitoring is disabled.

options

object

Options.

Properties

Name	Type	Description
`interval`	number	User defined iteration interval. In milliseconds. Minimum of 1000 milliseconds.

enableMeshRoomMode(enabled)

Enables mesh room mode during conference.

Parameters:

Name	Type	Default	Description
`enabled`	boolean	false	Whether mesh room mode shall be used during conference.

fetchGeolocationInformation(positionOptions)

Returns a promise that gives the position for a geolocation request
https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition

Parameters:

Name	Type	Description
`positionOptions`	GeolocationPositionOptions	Optional position options object

Returns:

Geolocation position in a promise

Type: Promise.<GeolocationPosition> | Promise.<GeolocationPositionError>

fetchNetworkInformation(testServer, bandwidthRatingThresholds)

Returns a promise that gives the result for a network test.
This method is the recommend one to be used : testings are based on fetchNetworkInformation Version 1.

Parameters:

Name	Type	Description
`testServer`	string	Server used for the network test (optional)
`bandwidthRatingThresholds`	array	Thresholds used for rating. Default value is [300,500,1000,1500,2000]

Returns:

Network test result in a promise

Type: Promise.<NetworkInformation>

fetchNetworkInformation_v1(testServer)

fetchNetworkInformation Version 1. Returns a promise that gives the result for a network test
Adviced method to get a network estimation

Parameters:

Name	Type	Description
`testServer`	string	Server used for the network test (optional)

Returns:

Network test result in a promise

Type: Promise.<NetworkInformation>

fetchNetworkInformation_v2(testServer, bandwidthRatingThresholds)

fetchNetworkInformation Version 2. Returns a promise that gives the result for a network test
This version of the method is more precise on result but use more network ressources.

Parameters:

Name	Type	Description
`testServer`	string	Server used for the network test (optional)
`bandwidthRatingThresholds`	array	Thresholds used for rating. Default value is [300,500,1000,1500,2000]

Returns:

Network test result in a promise

Type: Promise.<NetworkInformation>

fetchProfileInformation(bearerToken, forceUpdate)

Returns cloud profile of this one.

Parameters:

Name	Type	Default	Description
`bearerToken`	string
`forceUpdate`	Boolean	false	forces profile update; optional, defaults to false.

Returns:

Profile information in promise

Type: Promise.<object>

fetchUserMediaDevices()

A promise for fetching user media devices which can be used for creating a Stream object
Use getUserMediaDevices() instead of this function

Deprecated:

Returns:

Type: Promise.<MediaDeviceList>

getBrowser()

get UserAgent browser name.

Returns:

Returns browser name

Type: String

getBrowserDetails()

get UserAgent browser details information.

Returns:

Returns browserDetails information : this can be used to determine if browser is based on Chromium

Type: String

getBrowserInfo()

get UserAgent browser information.

Returns:

Returns browser information

Type: String

getBrowserMajorVersion()

get UserAgent browser major version.

Returns:

Returns browser major version

Type: String

getBrowserVersion()

get UserAgent browser version.

Returns:

Returns browser version

Type: String

getCapabilities()

get UserAgent capabilities.

Returns:

Type: UserAgentCapabities

getCPUArchitecture()

get UserAgent CPU architecture information if available.

Returns:

Returns cpu architecture, could be one of the following : 68k, amd64, arm[64/hf], avr, ia[32/64], irix[64], mips[64], pa-risc, ppc, sparc[64] or undefined

Type: String

getCurrentSession()

Returns connected session for this UserAgent

Returns:

session Returns null if the UA is not connected

Type: Session

getDefaultDevices()

Returns UserAgent default devices

Returns:

Type: DefaultDevices

getDeviceModel()

get UserAgent device model if available.

Returns:

Returns device model

Type: String

getDeviceVendor()

get UserAgent device vendor if available.

Returns:

Returns device vendor, could be one of the following : Acer, Alcatel, Amazon, Apple, ... , Vodafone, Xbox, Xiaomi, Zebra, ZTE or undefined

Type: String

getEngineName()

get UserAgent browser engine name if available.

Returns:

Returns browser engine name, could be one of the following : Amaya, Blink, EdgeHTML, Flow, Gecko, Goanna, iCab, KHTML, Links, Lynx, NetFront, NetSurf, Presto, Tasman, Trident, w3m, WebKit or undefined

Type: String

getEngineVersion()

get UserAgent browser engine version if available.

Returns:

Returns browser engine version

Type: String

getEnterprise()

Returns user agent enterprise (set when registered using 'apirtc:' URI)

Returns:

enterprise Will be set to null if no enterprise is set

Type: Enterprise

getEventCenter()

Returns eventCenter for this UserAgent

Returns:

Returns EventCenter

Type: EventCenter

getOsName()

get UserAgent OS name.

Returns:

Returns OS name

Type: String

getOsVersion()

get UserAgent OS version.

Returns:

Returns OS version

Type: String

getPhotoUrl()

Returns photo URL of this one.

Returns:

photo URL on success, null otherwise.

Type: string

getUserData()

Returns user agent user data

Returns:

contact's userdata

Type: Object

getUserMediaDevices()

return user media devices

Returns:

Type: MediaDeviceList

getUsername()

Returns user agent username

Returns:

username

Type: String

getWhiteboardClient()

Returns whiteboard client

Returns:

WhiteboardClient

Type: WhiteboardClient

isRegistered()

Tests whether the UserAgent represented by this one is registered.

Returns:

true if UA is already registered.

Type: boolean

on(listener)

Adds a listener to a Observable event

Parameters:

Name	Type	Description
`listener`	function

Inherited From:

Observable#on

Overrides:

Observable#on

Returns:

this instance for chaining

Type: Observable

register(options)

Register a UA to the server. If the User Agent URI is prefixed with 'apirtc:', a password has to be specified in the options

Parameters:

Name	Type	Description
`options`	RegisterInformation	all user connection options

Returns:

Connected Session in a promise

Type: Promise.<Session>

Example

user1.register({
         password: 'aaaa'
     })
     .then((session) => {
         // OK : UserAgent is connected to the ApiRTC platform
     })
     .catch((error) => {
         // error : UserAgent could not be connected to the ApiRTC platform
     });

removeListener(eventType, listener)

Remove existing listener to Observable event

Parameters:

Name	Type	Description
`eventType`	String
`listener`	function

Inherited From:

Observable#removeListener

Overrides:

Observable#removeListener

Returns:

this instance for chaining

Type: Observable

setOverallIncomingVideoBandwidth(bandwidth)

Sets video bandwidth limitation for the overall incoming traffic.

Parameters:

Name	Type	Description
`bandwidth`	number	bandwidth usage in kilobits per second.

Returns:

Type: void

setOverallOutgoingVideoBandwidth(bandwidth)

Sets video bandwidth limitation for the overall outgoing traffic.

Parameters:

Name	Type	Description
`bandwidth`	number	bandwidth usage in kilobits per second.

Returns:

Type: void

setPerCallIncomingVideoBandwidth(bandwidth)

Sets video bandwidth limitation for incoming traffic (on per-call basis).

Parameters:

Name	Type	Description
`bandwidth`	number	bandwidth usage in kilobits per second.

Returns:

Type: void

setPerCallOutgoingVideoBandwidth(bandwidth)

Sets video bandwidth limitation for outgoing traffic (on per-call basis).

Parameters:

Name	Type	Description
`bandwidth`	number	bandwidth usage in kilobits per second.

Returns:

Type: void

setPhotoUrl(url)

Set user agent photo url

Parameters:

Name	Type	Description
`url`	string

Returns:

Type: void

setTargetBandwidthUsage(kbps)

Set target bandwitdh usage for video calls (700 is default, be sure to set at least to 300)

Parameters:

Name	Type	Description
`kbps`	number	Target bandwitdh usage for video calls in kbps

See:

setOverallIncomingVideoBandwidth
setOverallOutgoingVideoBandwidth
setPerCallIncomingVideoBandwidth
setPerCallOutgoingVideoBandwidth

Returns:

Type: void

setUserData(userData)

Sets user data for this user session
User data is visible from other users

Parameters:

Name	Type	Description
`userData`	Object

Returns:

Type: void

setUsername(username)

Set user agent username

Parameters:

Name	Type	Description
`username`	string

Returns:

Type: void

startPrecallTest(precallTestTerminated, enableCamResolutionTest, maxVideoBandwidth, audioSourceId, videoSourceId)

Runs Precall test

Parameters:

Name	Type	Description
`precallTestTerminated`	callback
`enableCamResolutionTest`	boolean	true to execute camera resolution test, false otherwise
`maxVideoBandwidth`	number	video bandwidth limitation of the auto webrtc call
`audioSourceId`	string	video device ID
`videoSourceId`	string	audio device ID

startWhiteboard()

start Whiteboard. This enable whiteboard feature in an offline mode.

Properties:

Name	Type	Default	Description
`canvasId`	string		Identifier of the canvas to use for whiteboard
`cursorColor`	string	invisible	User cursor color, sets the user cursor color that will be seen by other participants. Set to '#000000' to have a black cursor.

stopWhiteboard()

stop Whiteboard. Stop whiteboard feature.

unregister(options)

Unregisters this UserAgent

Parameters:

Name	Type	Description
`options`	DisconnectOptions

Returns:

Type: Promise.<void>

Example

Unregister n UserAgent

ua.unregister()
     .then(() => {
         // OK : UserAgent is disconnected from the ApiRTC platform
     })
     .catch((error) => {
         // error : an error occured during unregistration
     });

updateMediaOnCall(callId, callId)

Update media stream during a call. If changing video bandwidth during call, use setTargetBandwidthUsage before updating the media stream.

Parameters:

user1.setTargetBandwidthUsage (1000);
user1.updateMediaDeviceOnCall(callID, localStream.userMediaStreamId);

Change video bandwidth during call
Name	Type	Description
`callId`	number	call ID.
`callId`	number	local stream ID. @example

Returns:

Type: void

Events

ccsConnectionStatus

Fired when ccs Connection status change. This can be an insteresting information to detect network failure.

Type: object

Properties:

Name	Type	Description
`status`	string	status of the CCS connection : connected, disconnected, error, retry

externalJsLoadingStatus

Fired when externalJs loading status change. This can be an insteresting information to detect network failure.

Type: object

Properties:

Name	Type	Description
`extjs`	string	external js concerned by the event
`status`	string	status of the loading : loaded, error, retry

mediaDeviceChanged

Fired when user media list have changed. call getUserMediaDevices() to get an updated MediaDeviceList

Type: object

Properties:

Name	Type	Description
`added`	array	array of added input/ouput
`removed`	array	array of removed input/ouput
`updated`	array	array of updated input/ouput
`updateReason`	String	give an updated reason. Value can be 'updatedOnDeviceChange' or 'updatedAfterGetUserMediaSuccess'
`firstMediaDeviceListInitialization`	Boolean	indicate of this is the first event occurrence with a real list from device