Weemo abstracts session management and video call creation across the platforms it supports. By doing so, a consistent object model is presented across many different devices. This simplifies the implementation and validation process for the developer, and provides a consistent experience for the user. The platforms Weemo supports include browsers, iOS and Android.
This article will focus on key events that occur when using the Javascript API in a WebRTC-enabled browser. We will describe common Weemo session lifetime events and typical Weemo Video-call events. Becoming familiar with these sequences in the Javascript API is a great place to start to understand all of the platforms that Weemo supports.
Background
Each of the SDK platforms requires the programmer to instantiate a singleton Weemo Object. While the language bindings of the SDK platforms vary, the Weemo object exposes two important callbacks that you can use to manage a Weemo session and handle Video calls. In Javascript these are called:
[code]
onConnectionHandler
onCallHandler
[/code]
onConnectionHandler Callback
The
onConnectionHandler callback is used to report transitions in the state of the Weemo session. These changes include the events when the Weemo session connects to the cloud, when the user becomes authenticated and when a WebRTC video endpoint has been established for the user.
A basic
onConnectionHandler callback is presented below. It shows a simple implementation that primarily prints log messages. The most important point to notice here is the call of
weemo.authenticate() after the
connectedWebRTC message arrives.
It is not until the Weemo objects reports
connectedWebRTC that it is appropriate to complete user authentication. (Recall that in our previous post, we instantiated the Weemo object with the authentication credentials. Here, we ask for these to be validated, after a connection has been established.)
[code]
weemo.onConnectionHandler = function(message, code) {
switch(message) {
console.log("onConnectionHandler:" + message);
case 'connectedWebRTC'
console.log("onConnection: connectedWebRTC");
weemo.authenticate();
break;
case 'sipOk':
console.log(WebRTC Video Endpoint Established');
break;
}
}
}
[/code]
The series of
messages that you will see in the console log in a normal session are described below. While a detailed understanding of these events is not needed to get started with Weemo, it is helpful to know what they mean.
- hapOk - the Weemo Realtime Platform has been detected
- probesOk - the Weemo Realtime Platform latency checks have been performed
- connectedWebRTC - a WebRTC video session has been established with the
Weemo Realtime platform
- connectedCloud - the Weemo singleton object has established a
connection with Weemo Web Services
- authenticated - user identify has been confirmed with Weemo Web
Services
- sipOk - ready for video calls
In the above descriptions, the Weemo "Realtime Platform" is the collection of servers and services that route the media of a video call. Weemo "Web Services" confirm identity, track presence and grant access to the Weemo Realtime Platform. You can see that the API coordinates accesses to a variety of services in order to set up a single reliable video call.
onCallHandler Callback
The onCallHandler callback is used to report the arrival of a new call, and also to report changes in the status of an existing call. The outline of a basic onCallHander is shown below. Once again, this handler is instrumented to print log messages.
[code]
onCallHandler = function(callObj, callInfo) {
console.log(callInfo.status + "(" + callInfo.type + ")");
if (callInfo.status == 'incoming') }
if confirm("Do you want to accept the call?") {
callObj.accept();
}
else {
callObj.hangup();
}
}
[/code]
The most important thing that the onCallHandler
must do is accept an incoming call! Weemo's default implementation of the
onCallHandler displays the confirm prompt for accepting calls. It is a common error for our new users to override the onCallHandler to observe the events, and forget to
accept() the call.
Instrumenting the
onCallHandler with log messages is a good way to learn about the events of a video call. In a normal incoming call scenario, here are the series of messages you will see in a WebRTC-enabled browser.
- incoming(WebRTCcall) - a new video call is arriving
- active(WebRTCcall) - the video call is established and the
conversation is proceeding.
- terminated:(WebRTCcall) - the call has been ended. This callback
is returned regardless of which user ends the call.
Conclusion
This article described the callback handling mechanism and key event types used for managing Weemo Sesssions and Weemo Video calls. Here, we focused on the callback mechanism of the Javsascript API: callback functions. On other platforms the mechanism is whatever is most natural on the platform. For iOS, a Delegate protocol is defined, and for Android, Weemo provides Events. The names of the events, status codes and operation sequences are similar across all platforms and helps to enable the rapid development and deployment of video capabilities across a wide range of devices.
