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.

Integrating WebRTC

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.

API Classes

AculabCloudClient

Constructor

  • 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.

Functions:

  • isSupported

    static boolean AculabCloudClient.isSupported()

    Returns true if the browser supports the necessary functionality and false if not.

  • getCodecList

    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".
  • callClient

    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
  • callService

    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
  • makeOutgoing

    AculabCloudOutgoingCall AculabCloudClient.makeOutgoing(serviceName)

    Deprecated. An alias for callService() for backwards compatibility with version 2 API.

  • enableIncoming

    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.

  • disableIncoming

    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.

Properties:

  • iceServers

    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.

  • maxConcurrent

    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.

Callback Properties:

  • onIncomingState

    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
  • onIncoming

    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.

AculabCloudCallOptions

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.

Properties:

  • localStream

    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.

  • 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.

  • receiveAudio

    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.

  • receiveVideo

    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.

  • maxBitrateAudio

    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.

  • maxBitrateVideo

    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.

  • codecs

    AculabCloudCallOptions.codecs

    An object

  • codecs.audio

    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.

  • codecs.video

    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.

AculabCloudCall

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.

Functions:

  • callId

    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.

  • callUuid

    string AculabCloudCall.callId

    Gets the uuid used for the call.

  • mute

    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.
  • sendDtmf

    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.

  • disconnect

    void AculabCloudCall.disconnect()

    Disconnects the call. This can be called at any time.

Callback Properties:

  • onDisconnect

    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.
  • onMedia

    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.
  • onConnecting

    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.
  • onConnected

    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.

AculabCloudOutgoingCall

The class extends AculabCloudCall. This class represents outgoing calls and is returned by AculabCloudClient.callService() and AculabCloudClient.callClient().

Callback Properties:

  • onRinging

    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.

AculabCloudIncomingCall

The class extends AculabCloudCall. This class represents incoming calls and is passed in calls to the AculabCloudClient.onIncoming() callback.

Functions:

  • ringing

    void AculabCloudIncomingCall.ringing()

    Notify the calling service that the user is being alerted to the incoming call.

  • answer

    void AculabCloudIncomingCall.answer(options)

    Answer the incoming call.

    Parameter Description
    options When specified, an AculabCloudCallOptions object.
  • reject

    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.

⚠️ **GitHub.com Fallback** ⚠️