Class: UserAgent

UserAgent

User Agent

The UserAgent serves as the base to use apiRTC.
A user agent can be authenticated or not. For an ApiRTC cloud platform user , the uri is prefixed with 'apirtc:'.
He can be anonymous if it's a client of an ApiRTC cloud platform enterprise, use prefix apiKey: 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:
Returns:

Created object

Type
UserAgent
Example

Create an UserAgent

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

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. 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:
  • Yes
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:
Overrides:
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

Register an UserAgent

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:
Overrides:
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);
Name Type Description
callId number

call ID.

callId number

local stream ID.

  • @example
Change video bandwidth during call
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