ApiRTC Tutorial

WebRTC Phone : Second example :

In this example, we will see how to customize your phone for a better integration in your apps. We will use jQuery to manage our buttons. As for the first example, this demonstration is available on our server : example-2. You can have a quick test of our service by opening two tabs in your browser, you will then be able to establish a video call between your two webRTC client using the associated apiCCId number. The main differences with the first example is that we now manage the command buttons on the web side and use some of the events handlers to be informed by apiCC of the call state (incoming call, remote hangup, error on user media access) Script below :

Second example : Explanation

Including ApiCC Javascript library

This part is almost identical to the first example, except that we also include jQuery in order to manage our buttons:

Script below :

Web page definition

This part is almost identical to the first example, except that we replace the command “div” element by our buttons: Script below :

ApiCC script

1 – Session Creation

The initialization still has to be done, just as in the previous example :

Script below :
For clarity, we use a named function for onReady parameters : sessionReadyHandler. This will be the executed function Script below :

Session object is defined in ApiCC library :ApiCCSession

2 – Adding audio & video support – WebRTC Support

As in example 1, WebRTC support on your application is added by a webRTCClient creation on your session. This is done on the onReady function handler “sessionReadyHandler” as a session needs to be established before webRTCClient creation.

Scripts below :

The only difference is that in this case, we don’t provide any command div descriptor as it will be managed on Web side. In order to be able to get call state of your phone and be able to customize our command buttons, we will add events listeners before the webRTCClient creation :

Associated handlers to theses events listeners have to be defined : In incomingCallHandler(), we add a new event listener on “remoteHangup” to be informed when the other person of the call hangs up. In this example we then modify the buttons appearance, enabling one and disabling the other.

In userMediaErrorHandler(), we are informed that the user has not granted access to the media so we modify again the buttons activation :

In remoteHangupHandler(), we are informed that the other person hung up the phone, so we modify the buttons activation if it was the latest established calls (several simultaneous calls are possible on a conference use case)

The last bits of code to add, in order to finish a complete phone, are the functions executed when the user clicks on our buttons.

On “call” button click : we execute the call() function of our webRTCClient in order to call the number present in the input element and we also modify the buttons activation :

On “hangup” button click : we execute the hangUp() function of our webRTCClient in order to hangup all the established calls and we modify buttons activation :

WebRTC Client object is defined in ApiCC library :ApiCCWebRTCClient

Complete description of all available features are included in the API description. For instance to set the media routing mode to turn, you simply have to use setMediaRoutingMode () function :






Simple Instant messaging client :

This example will show you how to easily create a Chat service using apiRTC.

As for the others examples, this demonstration is available on our server : example.

You can test the example by opening the above link in two different tabs in your browser. You will then be able to chat between your two instant messaging client (using the associated apiCCId number).

The base of the script is the same as before. It begins with importing ApiRTC, and we also include the twitter bootstrap library here, to show a simple chat box :

Then we load the html chat box, but it will be hidden at first :

We then create an IMClient with ApiRTC, after binding the “receiveIMMessage” event to our custom handler :

When the “createBox” button is clicked, we want the box to pop up, and to be able to enter in communication with the remote client :

With our IMClient created and our box open, we can now send messages to the remote client. After the users enters a message, the following function is executed to send it :

A symmetrical behavior is then expected of the remote client, which has also created it’s IMClient, and has registered an event handler with the event “receiveIMMessage”. The receiveIMMessageHandler function initializes the IMClient if necessary, and then displays the message received :

The communication is now established between the two clients, and they can continue exchanging messages. To go further, you can also check our group chat example. [/tab] [tab]

Presence management :

Getting presence status of your contacts is really simple with ApiRTC. Presence can be known by adding an event listener on ‘updatePresence’ [box]

function updatePresenceHandler(e) {
 console.log('updatePresenceHandler :' + e.detail.connectedUsersList);
apiCC.addEventListener("updatePresence", updatePresenceHandler);

[/box] [/tab]   [tab]

Using events :

Using events is really simple : [box]

function incomingCallHandler(event) {
   if(event.detail.autoAnswerActivated === false) { 
apiRTC.addEventListener("incomingCall", incomingCallHandler);

[/box] the handler “incomingCallHandler()” is called when an event “incomingCall” is fired, you can then access detail of the event using “event.detail.” Ex : event.detail.autoAnswerActivated for an incomingCall event Check description of the events in the API Documentation to learn about the available parameters on the different events. [/tab]   [tab]

Select media :

It is possible to choose a media to use (specific microphone or camera), and ApiRTC provides helper functions for that. The following code sample allows a user to select his preferred camera and microphone. His choice is also remembered, should he refresh the page. The complete code is below :

You notice that most of the code and event handlers was already present in the second audio/video example. Selecting a media shows a complete example of how to interact with ApiRTC in order to customize it’s behavior.

The first interesting snippet is the request made to ApiRTC to get the list of the available media devices (microphones and cameras) :

This line is called when ApiRTC is initialized, and will have as parameters the audio and video sources available to ApiRTC, exposed by the webRTCClient.
In the gotSource function that we defined, the different options are then displayed in the selectors, so that the user can choose it’s microphone and camera. His choice is also retrieved from the localStorage if there was one.

When the user clicks one of the selectors, his new choice is also stored in the localStorage. The consequence is that the user preference is persistent after a page refresh. When the user changes it’s choice, the information has to be forwarded to ApiRTC, so that the preferred camera and microphone will be used.

This is the purpose of the following function call (for the audio). We also store it in the localStorage.

The audioSourceIdInLocalStorage variable must be one of the Ids sent as parameters from the getMediaDevices function (the gotSources parameter) function. This way, during the subsequent calls, ApiRTC will use the specified device. There is a similar mechanism to choose the video source using the setVideoSourceId function.

The last step is to instruct ApiRTC to use a particular device. This is done via the following function :

[/tab] [tab]

Group Chat :

The next example show how to realize a simple group chat between several clients.

Note : this feature is only available in the Enterprise version. See the feature comparison for more information.

Please make sure that you went through the simple chat tutorial before the group chat tutorial, as many parts are the same between those two examples. In particular, the creation of the IMClient and subscription to some events is the same. In a group chat, the steps are :

  • One client creates a group chat
  • This client then makes other clients join it’s newly created group chat
  • Messages exchanged between clients on the group chat are sent to all the participants for the duration of the group chat.
  • A client can leave the group chat at any time. The group chat will be destroyed when the last client leaves.

There are 4 clients for this example, which can be found on Github. The difference is that we use the group chat specific events :

There are five new events used here. The group chat creation is triggered by a click on the “createGroupChat” button.
When the user 1 clicks it, it invites the users 2 and 3 to a group chat. The user 4 can be added later, via the “addUserInGroupChat” button. A group chat is active as long as there are participants in the group. And a client can leave the group chat at any time (“leaveGroupChat”).

After subscribing to these events, we can also bind our buttons to our instance of IMClient. This will allow the client to create and joins a group chat. Once in a group chat, a client is also able to invite other participants.

The client also needs to register to some events to be notified when (in order) :

  • A client is added in a group chat
  • The group chat is created
  • An invitation to join a group chat is received
  • A message is received in the group chat
  • The status of a member of the group chat changes

Note that the groupChatHandler function only displays the incoming messages in the console ! You have to open your browser console to see the messages.

[/tab] [tab]


We also offer a shared whiteboard in real-time between clients bundled with ApiRTC.

Note : this feature is only available in the Enterprise version. See the feature comparison for more information.

Sample clients are available directly on Github. Please open them in parallel, to be able to follow the explanations in good conditions.
We have two clients exchanging drawings in real-time.

The first bit to notice it the creation of a canvas. This will be the underlying support for our whiteboard. The mouse events will be recorded and drawn locally, but also sent to the remote client and re-played in it’s canvas.

The creation of a “whiteBoardClient” is necessary. Then it can be used like the other clients in ApiRTC, for instance :

The whiteBoard client relyes on the room system to transmit messages between participants.
After creating the whiteBoardClient, the process is started in the roomCreationHandler :

After the creation, and invitation it will be possible for the client whose Id equals 1 to send commands to the client 2. In this example we bind the click event of some buttons to these orders :

Notice the use of the dataClient : this is used to send arbitrary data (in JSON format) to the remote client. It has one method (sendData) and one event (receiveData).

This allows us to make custom commands between clients. In this example, the client1 is able to send commands to the client 2. Several commands are available : “takeSnapshot”, “clearPaper”, “audioRecord”… Using the sendData function, the client is able to send orders to the other client.

The client 2 can then take specific actions when receiving the orders :

It is possible to define your own set of custom commands very easily by reusing the connection between the clients.
In this example, the client can for instance make a snapshot of it’s local stream, and upload it to our servers.
It will then be transmited to the other client, who will be able to draw on the photo it in real-time.

For the function to be called, the corresponding event listeners like the receiveDataHandler have to be registered on the remote client too :

Some events are related to the the possibility to take a snapshot. Check out the docs of the whiteBoardClient. It is useful to allow the remote client to draw on a static image. This has proven useful in our remote support solutions, for instance when a technician assists an operator.

Want to learn more ? Contact us at Apizee.com : we have more advanced functionalities (in beta).


[/tabcontent] [/tabs]