2/20/2014

Getting Started with Weemo and WebRTC: Part 2 - Callbacks

Katie Smart's profile picture
Katie Smart Sr. Manager, Global Marketing Communications
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.html5 webrtc 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. 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.

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.

Next Up