Monday, January 13, 2014

Using Ripple to emulate Apache Cordova / Phonegap applications.

Apache Ripple

After somegap I had to use Ripple emulator when I was trying to upgrade GWTPhonegap to support Apache Cordova 3.3. Apache Ripple is a browser agnostic mobile emulator. This will enable rapid development of Hybrid mobile applications using frameworks like Apache Cordova and Blackberry webworks. Ripple was initially developed by Blackberry and then donated to Apache open source community. Similar to Apache Cordova, Apache Ripple is a free and Open sourced under the Apache License, Version 2.0


The latest version of Ripple is distributed using nodejs and so you need to install nodejs first. The instructions to install nodejs are available here.

After installing nodejs, open the command prompt/terminal and run the below command to install ripple emulator.

npm install -g ripple-emulator

And since you will be emulating Apache Cordova applications, you need to install Cordova and create a Apache Cordova application.The instructions to install Apache Cordova are available here.

Running Ripple

Once you create a Apache Cordova project, make changes to the code, add the platform, prepare the project running the below command.

cordova prepare

The above command needs to be run every time you make changes to your project.

Run the below command from the root of your project to start the Ripple emulator.

ripple emulate

Once you run the above command, ripple will launch the default browser on the system. Your application will be emulated in the browser launched.

Some times you may see the below error page after Ripple launches the browser.

Just click on 'Wait' button or refresh to resolve the error.


The devices section highlighted below provides options to emulate the application on different devices.

There is a option to select the device which we need to emulate. There are several Blackberry, Android and iOS devices available which can be emulated.

Also there is an option to simulate the vertical and horizontal orientation also.Just click on the vertical or horizontal  icon against Orientation label to simulate Vertical or Horizontal orientation.


The platform section provides options to choose the platform and version to be used for emulation.

The platform drop-down provides options to select a platform among WebWorks, Phonegap to emulate.

You can also select the version you want to emulate.Apache Cordova provides versions 1, 2 & 3. I believe all the versions between 1 and  2 can select 1 and so on.


The information section provides information about the environment that is being emulated.The description of  the information displayed is below.

Version: version of the application
Platform: The framework that is being emulated.
Device: The device that is being emulated.
OS: Operating system of emulated device.
Manufacturer: Manufacturer of the device that is being emulated.
Screen: The screen resolution of the emulated device.
Density: The pixel density in the app you are emulating.
CSS Pixel Ratio: The device pixel ratio is the ratio between logical pixels and physical pixels.This indicates the pixel ratio of the emulated device.
CSS Pixels:The CSS pixels that is being emulated.
User Agent: Indicates the user agent in device that is being emulated.


The accelerometer allows us to emulate the device motion changes using accelerometer  framework. You might as well emulate shaking the device to test the device motion changes. You can use the device icon in this section to emulate the device motion actions.


The 'Settings' has options to switch the themes between 'Light' or 'Dark' and you can turn the tool tips on or off.

Desktop browsers have a limitation which restricts the Ajax code from making cross domain requests. This is a security restriction on all the browsers. Chrome provides an flag to bypass that restriction. 

The Cross Domain Proxy is one of most useful features of the Ripple emulator. Ripple proxies the request made from then application, makes a request for the data from its own server and then proxies the result back to the application.

Device & Network Settings

This section provides you an option to emulate the network and gloabalization API of the Cordova framework.

You can select the connection type you want to select from all the connection types like ETHERNET, Wi-Fi, 2G, 3G, 4G and also you can indicate if there is a network lag or not.

There are also some functions from globalization API which can be emulated. You can provide the locale name, whether the day light savings are enabled or not and also the first day of the week. The values provided here will be used by your application when these functions are called.

Geo Location

The geolocation allows you to emulate the location related API in your application. You can enter the values to mock in the geolocation section and they will be used by your application.


The Ripple emulator reads the configuration file and displays the result in this section . If there are any errors or issues they will be displayed here.


The Events section provides several events(device ready, back button,pause, resume, search button, menu button, offline, online) which are supported by Apache Cordova. While these events are not actually simulated, they are just registered. Say if you select back button, the event will be registered to the Cordova API, but it doesn't simulate the actual hardware event.


Ripple supports some of the functions related to Camera API also. It allows you to select a image from your system and then use it for mocking the functionality later.

Unsupported options

As you can see by now, Ripple doesn't support all the options provided by Apache Cordova. When Ripple encounters a call that it doesn't support, it shows up a pop up similar to below.

In this case you can enter the JSON object to the callback that you want to execute.


Ripple is an excellent development tool to emulate the Apache Cordova applications on desktops. You will be able to switch between different OS's like Android, i-OS and Blackberry. And you will able to get a first hand feel of how your application looks on different devices and also in horizontal and Vertical orientations. There may be some limitations in Ripple, but I believe it is a must use tool for developers developing cross platform mobile applications using Apache Cordova. And once you are done with developing, you need make sure you will test the application on real device before pushing the applications to App Stores.


  1. Hi Kiran, I work as a developer developing Hybrid mobile app using sencha touch/cordova/phonegap. I find this ripple emulator chrome extension to be very useful during my development phase. Since it is just a chrome ext, it did not need any installations as you clearly explained above, and it seems to present all the options as you explained above. Did you ever try using Ripple Emulator Chrome ext? are there any clear advantages of this ripple installation over chrome ext?


    1. Hi Vinod,

      I agree there is Chrome extension for Ripple Emulator.But the latest version of Ripple switched over to nodejs and the steps I described below are for the latest version of the Ripple emulator. And using these steps you can run Ripple emulator on any browser not just Chrome.