WebRTC Interface Version 3 Application Developer Guide - aculab-com/aculab-webrtc GitHub Wiki

• How to Write WebRTC Apps
• Integrating WebRTC
• Video calls between WebRTC Client instances
• Creating a WebRTC Client Instance
• Enabling Incoming Calls on a WebRTC Client Instance
• Calling a WebRTC Client instance from WebRTC
• Calling an Aculab Cloud Service from WebRTC
• Calling a WebRTC Client Instance from Aculab Cloud
• Accepting an Incoming WebRTC Call
• Call Control Callbacks
• Disconnecting a Call
• Call costs
• Troubleshooting

This guide shows the basic steps how to write WebRTC applications for Aculab Cloud. Refer to the API guide for detailed documentation on the APIs used.

WebRTC Client instances can call, and be called from, Aculab Cloud services and other WebRTC Client instances. They cannot call PSTN or SIP phones directly, although of course Aculab Cloud services can call those devices.

Each WebRTC Client instance can be configured to handle multiple concurrent calls, and a web page can multiple WebRTC Client instances. The maximum number of concurrent calls is browser dependent. The code shown in this guide handles only one WebRTC Client instance with one call.

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.

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

• In your HTML page, create a HTMLMediaElement element by adding one of the following:

  <video id="player"></video>

  or

  <audio id="player"></audio>

The default behaviour of the interface is to set up audio only calls. When the call is between two WebRTC Client instances, you can enable video in both or just one direction.

To make a call with video to a WebRTC Client instance you need to pass a suitably configured AculabCloudCallOptions object to AculabCloudClient.callClient(). The constraints property of the options object is passed to the browser's getUserMedia() function.
For example:

var options = {
    constraints: {
        audio: true,
        video: true
    }
};
call = acc.callClient("other_client_id", token, options);

For incoming calls from WebRTC Client instances, you can determine the caller's media settings for the call from the object passed to the onIncoming callback. For a call with video in both directions, the offeringVideo and canReceiveVideo properties of that object will be true. To answer the call with video, you need to pass a suitably configured AculabCloudCallOptions object to AculabCloudIncomingCall.answer().
For example:

var options = {
    constraints: {
        audio: true,
        video: true
    }
};
call.answer(options);

Note that calls will fail if the constraints require a local video stream but the user doesn't have a webcam, or refuses access to it. To receive video but not send it, you can use:

var options = {
    constraints: {
        audio: true,
        video: false
    },
    receiveVideo: true
};

To create a WebRTC Client instance, you will need the following information:

All WebRTC Client instances use the AculabCloudClient class. Create a new instance of the class with:

var cloudId = "1-2-0";
var webRtcAccessKey = "3krt4sfjo...";
var clientId = "myClient-4369";
var logLevel = 2;
acc = new AculabCloudClient(cloudId, webRtcAccessKey, clientId, logLevel);

where logLevel is between 0 and 6 inclusive. 0 disables logging.

If you will be accepting incoming WebRTC calls, then you need to set up the onIncoming and onIncomingState callbacks.

acc.onIncoming = newCall;
acc.onIncomingState = incomingState;

See Accepting an Incoming WebRTC Call for information on the newCall and incomingState functions.

A WebRTC Client instance needs a token to be able to receive incoming WebRTC calls. This token is retrieved from the webrtc_generate_token Web Services API. It should be generated by server side code, so the client does not know your web services API access key. An example as follows:

fetch('/get_webrtc_token_for_client', {
    method: 'POST',
    body: clientId
  })
  .then(response => response.json())
  .then(data => acc.enableIncoming(data.token));

The onIncomingState callback is used to notify you if incoming WebRTC calls are enabled or disabled.

WebRTC Client instances can call other WebRTC Client instances. This is achieved by calling AculabCloudClient.callClient() then setting up the AculabCloudOutgoingCall callbacks to handle the call control events.

A WebRTC Client instance needs a token to be able to call another WebRTC Client instance. This token is retrieved from the webrtc_generate_token Web Services API. It should be generated by server side code, so the client does not know your web services API access key.

An AculabCloudCallOptions object can be passed to configure the media settings. For example, this can be used to make video calls by requesting access to the user's webcam.

var options = { constraints: { audio: true, video: true } };
call = acc.callClient("other_client_id", data.token, options);
call.onDisconnect = callDisconnected;
call.onRinging = callRinging;
call.onMedia = gotMedia;
call.onConnecting = connecting;
call.onConnected = connected;

See Call Control Callbacks for information on these callbacks.

Such calls are charged for. See Call costs for information on finding these costs.

WebRTC Client instances can call Aculab Cloud inbound services. This is achieved by calling AculabCloudClient.callService() then setting up the AculabCloudOutgoingCall callbacks to handle the call control events.

call = acc.callService(encodeURIComponent("incoming_service_name"));
call.onDisconnect = callDisconnected;
call.onRinging = callRinging;
call.onMedia = gotMedia;
call.onConnecting = connecting;
call.onConnected = connected;

See Call Control Callbacks for information on these callbacks.

UAS and REST applications can call a WebRTC Client instance by setting the call destination to webrtc:<clientId>.

The Caller ID specified is passed to the onIncoming callback.

Calling a WebRTC Client Instance from the REST API Version 2.0

An example of using the Connect action to call a WebRTC Client instance, written in Python.

my_connect = Connect()
my_connect.set_next_page("/call_finished")
my_connect.append_destination("webrtc:{0}".format(clientId))
my_connect.set_call_from('441234567890')
my_connect.set_hold_media(Play(file_to_play='holdmusic.wav'))
my_connect.set_secondary_call(SecondaryCall(first_page=WebPage(url='secondary_first'),
                                            final_page=WebPage(url='secondary_final'),
                                            error_page=WebPage(url='error_page')))

Calling a WebRTC Client Instance from the UAS API

A Python example of using the UASCallChannel object to call a WebRTC Client instance.

if channel.start_call('webrtc:{0}'.format(clientId), call_from='441234567890') is True:
    # we have started an outbound call
    pass

onIncomingState

onIncomingState is used to inform you whether incoming WebRTC calls are enabled or disabled.

function incomingState(obj) {
    if (obj.ready) {
        // We can receive incoming calls
    } else {
        // We cannot receive incoming calls
        // Report obj.cause to the user
    }
}

onIncoming

If WebRTC Client has been configured to accept incoming calls, then the onIncoming callback is used to accept any incoming call.

The onIncoming callback should set up the AculabCloudIncomingCall callbacks, notify the user of the call, and send the ringing notification to the remote end.

// newCall has been assigned to the onIncoming callback above
function newCall(obj) {
    call = obj.call;
    callerId = obj.from;
    inbound = true;

    // Set up callbacks
    call.onDisconnect = callDisconnected;
    call.onMedia = gotMedia;
    call.onConnecting = connecting;
    call.onConnected = connected;

    // Play a ringing to notify user of the call
    // get the HTMLMediaElement element
    var player = document.getElementById('player');
    if (player.canPlayType('audio/wav')) {
        player.loop = 'loop';
        player.src = 'audio/ringing.wav';
        player.type = 'audio/wav';
        player.load();
        var p = player.play();
        if (p !== undefined) {
            p.catch(error => {
                // Handle error
            });
        }
    } else {
        // Browser can't play audio/wav
    }

    // Send ringing notification to the caller
    call.ringing();
}

See Call Control Callbacks for information on these callbacks.

Answering the call

When the user accepts the incoming call the call's answer() function needs to be called. For calls from WebRTC Client instances, an AculabCloudCallOptions object can be passed to configure the media that is sent.

The various call control callbacks have been set up in the code snippets above. Example code showing how these callbacks are implemented is shown in this section.

onDisconnect

This callback is called when the call has been disconnected. The player element should be reset, and any resources cleaned up.

function callDisconnected(obj) {
    // Notify the user that the call has disconnected.

    // Stop anything that is playing
    stopPlayer();

    // reset state
    call = null;
    inbound = false;
    isconnected = false;
}

// Function to stop the HTMLMediaElement element playing.
// This is used by the callDisconnected and gotMedia callbacks.
function stopPlayer() {
    // Get the HTMLMediaElement element
    var player = document.getElementById('player');

    // Reset the player state
    player.pause();
    player.loop = '';
    player.src = '';
    player.srcObject = null;
    player.type = '';
    player.load();
    playing_ringing = false;
    gotremotestream = false;
}

onRinging

If you have not got an media stream from the remote end, then you can generate a ringtone locally.

function callRinging(obj) {
    // get the HTMLMediaElement element
    var player = document.getElementById('player');
    if (!playing_ringing) {
        if (player.canPlayType('audio/wav')) {
            // Play a ringback tone if we have not got an audio stream
            // from the remote end
            // gotremotestream is initialised in gotMedia()
            if (!gotremotestream) {
                player.loop = 'loop';
                player.src = 'audio/ringback.wav';
                player.type = 'audio/wav';
                player.load();
                var p = player.play();
                if (p !== undefined) {
                    p.catch(error => {
                        // Handle error
                    });
                }
            }
        } else {
            // Browser can't play audio/wav
        }
        playing_ringing = true;
    }
}

onMedia

The onMedia callback is used to give you the remote media stream which you can connect to your HTMLMediaElement element.

function gotMedia(obj) {
    // Stop anything that is playing
    stopPlayer();

    var player = document.getElementById('player');
    gotremotestream = true;
    player.srcObject = obj.stream;
    player.load();
    var p = player.play();
    if (p !== undefined) {
        p.catch(error => {
            // Handle error
        });
    }
}

onConnecting

onConnecting is called when the browser has the local media stream and is preparing the sockets needed to transport the call media. There is nothing that specifically needs doing in this callback, but it can be used to connect the local media stream to show the camera view.

function connecting(obj) {
    // Update a web page element to notify the user that the
    // call is connecting
}

onConnected

When the call has been answered the onConnected callback will be called. You can use this callback to notify the user about call progress.

function connected(obj) {
    // Update a web page element to notify the user that the
    // call is connected
    isconnected = true;
}

Disconnecting a connected call is as simple as calling disconnect() on the call object. Inbound calls that have not connected should be rejected with a valid SIP cause, for example 486 busy here, instead.

function stopCall() {
    if (call) {
        // If inbound call has not been accepted, then reject the call
        if (inbound && !isconnected) {
            call.reject(486);
        } else {
            call.disconnect();
        }
    }
}

Calls from one WebRTC Client instance to another will incur costs. These can be found in CDR reports or by calling the application status web service. Each WebRTC call will be identified using an application instance id based on your WebRTC access key and the call Id of the call. The call Id can be obtained by calling callId() on the AculabCloudCall object. This data is then combined as "webrtc-<webrtc access key>.<call Id>".

In a CDR report the "Call ID" for each call is the application instance id with the call Id appended in the form "webrtc-<webrtc access key>.<call Id>.<call Id>".

For example, with a WebRTC access key of "1234567890abcde1234567890" and a call Id of "abc123abc" then the application instance id would be "webrtc-1234567890abcde1234567890.abc123abc" and the Call ID would be "webrtc-1234567890abcde1234567890.abc123abc.abc123abc".

A number of common issues can cause problems with media in a WebRTC call.

HTML5 autoplay blockers will prevent the HTMLMediaElement element from automatically playing the media from the remote end. Ensure that any blockers are disabled for your WebRTC page.

If the same username is registered from more than one browser instance then the most recently registered instance will receive incoming WebRTC calls. As WebRTC Client instances are automatically re-registered at various intervals, the most recently registered instance may change without warning. Therefore, in general it's best to register a given username with only one browser instance at a time.