WebRTC Interface Version 3 - aculab-com/aculab-webrtc GitHub Wiki
The interface consists of several JavaScript classes. These classes hide the complexity of the browser's WebRTC APIs and the differences in implementation between the supported browsers. The classes also handle the call set-up and tear-down, with the host page being informed of the call progress by means of callbacks.
The callback properties of each object instance must be either null or a function. When an event occurs, the function will be passed a single object parameter. Information about the event is included as properties of that object. All such properties are detailed below.
Implementations of WebRTC are still evolving and each browser has different levels of support for codecs and other WebRTC features. Before deployment, please be sure to try out our WebRTC interface in the environment where you expect to use it.
You can include the JavaScript library by adding the following line to your HTML header:
<script src="https://webrtc.aculabcloud.net/js/3/AculabCloudCaller.js" type="text/javascript"></script>
The version 3 library is backwards compatible with the version 2 interface and also includes an implementation of the version 1 interface.
The Application Developer Guide describes how to write applications that use the WebRTC Interface.
- AculabCloudClient
- AculabCloudCallOptions
- AculabCloudCall
- AculabCloudOutgoingCall
- AculabCloudIncomingCall
-
AculabCloudClient.constructor(cloudId, webRtcAccessKey, clientId, logLevel)
Creates an AculabCloudClient object
Parameter Description cloudId The identifier of the Aculab Cloud where services that interact with the user are located (e.g. 1-2-0). webRtcAccessKey The WebRTC access key of your Aculab Cloud account. clientId identifies this client object. It is the value that will be placed in the call_from field in the call details of the application's main channel when making calls to inbound services. It is also the value used when services make outbound calls to WebRTC clients. This can only contain alphanumeric and +-._ characters. logLevel A numeric value between 0 and 6 inclusive. 0 disables logging and 6 is the most detailed logging. This throws a string exception if any parameter is invalid.
-
static boolean AculabCloudClient.isSupported()
Returns true if the browser supports the necessary functionality and false if not.
-
static array AculabCloudClient.getCodecList(mediaType)
Returns an array of RTCRtpCodecCapability objects, if the browser supports the necessary functionality and an empty array if not. The list can be reordered to set a preferred codec and passed in an AculabCloudCallOptions object when placing or answering calls. (Note: removing items from the list is allowed but may cause inter-operability problems.)
Parameter Description mediaType Either "audio" or "video". -
AculabCloudOutgoingCall AculabCloudClient.callClient(clientId, token, options)
This initiates a call to the specified WebRTC Client instance. Call progress is reported by callbacks, these should be set on the object returned by this function.
Parameter Description clientId The client identifier of the WebRTC client that the call will be connected to. token The token is an authenication token. These are generated using an Aculab Cloud web service. options When specified, an AculabCloudCallOptions object This throws a string exception if:
- the browser doesn't support calling the cloud
- there are too many calls already in progress
- clientId contains disallowed characters
- token format is invalid
-
AculabCloudOutgoingCall AculabCloudClient.callService(serviceName)
This initiates a call to the specified Aculab Cloud incoming service. Call progress is reported by callbacks, these should be set on the object returned by this function.
Parameter Description serviceName The name of the Aculab Cloud incoming service that the call will be connected to. This throws a string exception if:
- the browser doesn't support calling the cloud
- there are too many calls already in progress
- serviceName contains disallowed characters
-
AculabCloudOutgoingCall AculabCloudClient.makeOutgoing(serviceName)
Deprecated. An alias for callService() for backwards compatibility with version 2 API.
-
void AculabCloudClient.enableIncoming(token)
This function initiates registration of this client object as the destination for calls to the clientId specified in the constructor. The status of the registration is reported by the onIncomingState callback.
Parameter Description token The token is an authenication token. These are generated using an Aculab Cloud web service. The token can be updated by calling this function with the new token. This throws a string exception if the token format is invalid.
-
void AculabCloudClient.disableIncoming()
This function initiates the removal of this client as the destination for calls to the clientId specified in the constructor. The status of the registration is reported by the onIncomingState callback.
-
AculabCloudClient.iceServers
Must be null or an array of RTCIceServer objects. This value can be changed at any time. Outgoing calls will use the value set when the call is made. Incoming calls will use the value set when the call is answered. If the value is null, an Aculab provided set of iceServers is used. Using an empty array will disable the Aculab provided iceServers.
-
AculabCloudClient.maxConcurrent
This is the number of concurrent calls this client is allowed to handle. The default is 1. This value must be 1 or greater. The upper limit is browser dependent.
-
AculabCloudClient.onIncomingState
Called when user registration state changes.
The object passed to the callback has the following properties:
Parameter Description ready A boolean indicating whether this client is waiting for incoming calls. casue The reason for the registration state change. retry A boolean indicating whether the client will automatically retry the registration. The property cause will be one of the following strings:
Cause Description 'DISCONNECTED' The connection to the cloud has been lost. 'INVALIDTOKEN' The token specified is not valid (for example, it has expired). 'FAILED' The registration was unsuccessful for some other reason. 'NORMAL' The state change was in response to API calls -
AculabCloudClient.onIncoming
Called when an incoming call occurs. If this is null or throws an exception, the incoming call is rejected.
The object passed to the callback has the following properties:
Property Description call An AculabCloudIncomingCall object. from The CallerID passed by the remote party. type The type of the remote party. One of "client", "service" or "other". offeringAudio The remote party is offering to send audio. canReceiveAudio The remote party can receive audio. offeringVideo The remote party is offering to send video. canReceiveVideo The remote party can receive video. The progress of the incoming call is reported by callbacks. These should be set on the passed call object before returning from the callback function.
These objects provide a means to configure the calls to other WebRTC Client Instances. Objects of this type are usually created using object literal notation as there is no constructor. All properties are optional.
-
AculabCloudCallOptions.localStream
A MediaStream object that is the local media to send to calls. If undefined, a media stream is obtained using getUserMedia() and the specified constraints.
-
AculabCloudCallOptions.constraints
A MediaStreamConstraints object used to obtain a local stream if required. The default is "{ audio: true, video: false }". This is unused if a localStream has been given.
-
AculabCloudCallOptions.receiveAudio
Can be true, false or undefined. When undefined the client will receive audio if the local stream has an audio track and refuse to receive audio otherwise. The default is undefined.
-
AculabCloudCallOptions.receiveVideo
Can be true, false or undefined. When undefined the client will receive video if the local stream has a video track and refuse to receive video otherwise. The default is undefined.
-
AculabCloudCallOptions.maxBitrateAudio
The maximum bitrate to use for audio. Set to Infinte to have no limit, undefined to use the browser default, or an integer which is in bits per second. The default is undefined.
-
AculabCloudCallOptions.maxBitrateVideo
The maximum bitrate to use for video. Set to Infinte to have no limit, undefined to use the browser default, or an integer which is in bits per second. The default is undefined.
-
AculabCloudCallOptions.codecs
An object
-
AculabCloudCallOptions.codecs.audio
An array of RTCRtpCodecCapability, such as that returned by getCodecList("audio"). The default is an empty array, which results in using the browser defaults.
-
AculabCloudCallOptions.codecs.video
An array of RTCRtpCodecCapability, such as that returned by getCodecList("video"). The default is an empty array, which results in using the browser defaults.
The base class for call objects. Instances derived from this object are returned by callService() and callClient() or passed in calls to the onIncoming callback.
-
string AculabCloudCall.callId
Gets the call identifier used for the call.
For outgoing calls, this may return undefined until the onConnecting callback gets called. It is always available for incoming calls.
-
string AculabCloudCall.callId
Gets the uuid used for the call.
-
void AculabCloudCall.mute(mic, outputAudio, camera, outputVideo)
Mutes audio and video for the call.
Parameter Description mic A boolean. If true, then the microphone (sent audio) is muted. If false, then the microphone is unmuted. outputAudio A boolean. If true, then the received audio is muted. If false, then the received audio is unmuted. camera A boolean or undefined. If true, then the camera track (sent video) has every frame filled entirely with black pixels. If false, then the camera track is sent unaltered. If undefined, the mic value is applied. outputVideo A boolean or undefined. If true, then the received video track has every frame filled entirely with black pixels. If false, then the received video is unaltered. If undefined, the outputAudio value is applied. -
void AculabCloudCall.sendDtmf(dtmfStr)
Sends DTMF characters.
Parameter Description dtmfStr A string containing the DTMF digits to be sent. Valid characters are 0,1,2,3,4,5,6,7,8,9,*,#,A,B,C and D. This throws a string exception if there is an invalid digit in the string.
-
void AculabCloudCall.disconnect()
Disconnects the call. This can be called at any time.
-
AculabCloudCall.onDisconnect
The call has disconnected.
The object passed to the callback has the following properties:
Property Description call The call object that is reporting the event. cause The reason the call disconnected. The property cause will be one of the following strings:
Cause Description 'MIC_ERROR' No microphone is available, usually because the user refused access or there is no microphone. 'BUSY' The service called hangup() with the busy cause or the service could not be started (due to limited UAS capacity, for example). 'UNOBTAINABLE' The specified incoming service name does not exist. 'MOVED' The service attempted to redirect the call. 'REJECTED' The call was rejected either by the incoming service or an intermediary. 'NOANSWER' The call did not connect. 'FAILED' The call was unsuccessful for some other reason. 'ERROR' An internal error occurred. 'NORMAL' The call has disconnected in the normal way after having connected. -
AculabCloudCall.onMedia
Called when remote media is available to be played to the user.
The object passed to the callback has the following properties:
Property Description call The call object that is reporting the event. stream A MediaStream object suitable connecting to a <video> or <audio> HTMLMediaElement as the srcObject. -
AculabCloudCall.onConnecting
Called once the local media stream has been obtained and the connection to the Aculab Cloud has been established. The browser will now start to prepare the sockets needed to transport the call media. The stream passed is the local media stream. This can be used to display the local camera view. The audio track should not be played to prevent echo.
The object passed to the callback has the following properties:
Property Description call The call object that is reporting the event. stream A MediaStream object suitable connecting to a <video> HTMLMediaElement as the srcObject. -
AculabCloudCall.onConnected
Called when the call has been answered.
The object passed to the callback has the following properties:
Property Description call The call object that is reporting the event.
The class extends AculabCloudCall. This class represents outgoing calls and is returned by AculabCloudClient.callService() and AculabCloudClient.callClient().
-
AculabCloudOutgoingCall.onRinging
Called when incoming service has signalled that the call is ringing.
The object passed to the callback has the following properties:
Property Description call The call object that is reporting the event.
The class extends AculabCloudCall. This class represents incoming calls and is passed in calls to the AculabCloudClient.onIncoming() callback.
-
void AculabCloudIncomingCall.ringing()
Notify the calling service that the user is being alerted to the incoming call.
-
void AculabCloudIncomingCall.answer(options)
Answer the incoming call.
Parameter Description options When specified, an AculabCloudCallOptions object. -
void AculabCloudIncomingCall.reject(cause)
Reject the incoming call.
Parameter Description cause The cause to give for rejecting the call. The value should be a SIP response code between 400 and 699 inclusive. If no cause is given or the specified cause is not a number, the cause 486 (Busy Here) will be used. This throws a string exception if the cause is not in the valid range.