Class: UserAgent

UserAgent

User Agent

The UserAgent serves as the base to use apiRTC.
A user agent can be authenticated or not. For an Apizee cloud user , the uri is prefixed with 'apizee:'.
He can be anonymous if it's a client of an Apizee enterprise and use prefix apzkey: as uri.
Once registered, its Session object can be used to communicate with other contacts using the platform on the same API key and CCS server


new UserAgent(options)

Create an User Agent

Parameters:
Name Type Description
options UserAgentOptions

all user connection options

Fires:

Extends

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. In dB. Default is 50 dB.


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 Description
enabled boolean

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)

Returns a promise that gives the result for a network test

Parameters:
Name Type Description
testServer string

Server used for the network test (optional)

Returns:

Network test result in a promise

Type
Promise.<NetworkInformation>

fetchProfileInformation(forceUpdate)

Returns cloud profile of this one.

Parameters:
Name Type Default Description
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:
  • Yes
Returns:
Type
Promise.<MediaDeviceList>

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

getEnterprise()

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

Returns:

enterprise Will be set to null if no enterprise is set

Type
Enterprise

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()

Test whether UA 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:
Returns:

this instance for chaining

Type
Observable

register(options)

Register a UA to the server. If the User Agent URI is prefixed with 'apizee:', 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

Register an UserAgent

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

removeListener(eventType, listener)

Remove existing listener to Observable event

Parameters:
Name Type Description
eventType String
listener function
Inherited From:
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

Deprecated:
  • Yes
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

startWhiteboard()

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

Properties:
Name Type Description
canvasId string

Identifier of the canvas to use for whiteboard

cursorColor string

User cursor color, sets the user cursor color that will be seen by other participants. Set to '#000000' to have a black cursor. Default value is invisible


stopWhiteboard()

stop Whiteboard. Stop whiteboard feature.


unregister(options)

Unregisters this UserAgent

Parameters:
Name Type Description
options DisconnectOptions
Returns:
Type
Promise.<void>
Example

Register an UserAgent

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

Events


ccsConnectionStatus

Fired when externalJs loading 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