Preview your app in Ripple


The Ripple emulator is a multi-platform mobile environment emulator that is custom-tailored to mobile HTML5 application development and testing. The Ripple emulator is an extension to the Google Chrome browser that allows you to quickly see how your application looks and functions on multiple mobile devices and platforms, while using BlackBerry WebWorks and PhoneGap APIs in a quick, browser-like environment. You can use the Ripple emulator to perform JavaScript debugging, HTML DOM inspection, automated testing, and multiple device and screen resolution emulation in real-time without redeploying the application or restarting the emulator. The Ripple emulator reduces the challenges faced by mobile developers caused by platform fragmentation in the marketplace.

The Ripple emulator includes a set of emulated APIs that reflect the APIs available on the platform you choose. For more information on the APIs supported for BlackBerry WebWorks applications in the Ripple emulator, see the API section.

Ripple emulator main page

Install the Ripple emulator

If you have already installed a previous version of the Ripple emulator and you have an Internet connection, you do not need to remove and reinstall the emulator. When you start it, it will upgrade automatically in the background. If it doesn't start automatically, you can go to the Extensions settings in the Google Chrome browser, and click Update extensions now.

  1. Download the Ripple emulator from the Downloads page.
  2. Start the Google Chrome browser.
  3. In the address bar of Google Chrome, paste chrome://extensions/ and then press Enter. The Google Chrome Extensions window opens.
  4. Open a file explorer window and navigate to the location where you downloaded the Ripple emulator file.
  5. Click the ripple_ui.crx file in the file explorer window (not in the downloads bar) and drag and drop it into the Google Chrome Extensions window. You may get an error message if you attempt to drag it from the downloads bar.
  6. When you are prompted to add the extension, click Add. If no prompt appears, clear the browser's cache and try dragging and dropping the ripple_ui.crx file again. If it still doesn't appear, clear your cache and restart the browser.

    Note: The Add window is a Google Chrome dialog box. The Ripple emulator does not use these mechanisms to access, store, or transmit any of your information.

    A Ripple button is added to your Google Chrome toolbar. You can now start using Ripple to test your BlackBerry WebWorks application.

Enable the Ripple emulator

Before you can test your app using the Ripple emulator, you need to start Ripple services.

  1. Start the Google Chrome browser.
  2. Click the Ripple icon beside the address bar.
    • If you see Start Ripple Services, click it and go to the next step.
    • If you do not see Start Ripple Services, it means that you have not yet accepted the EULA for the Ripple emulator.
      1. Navigate to any page that is on a web server (not a local file). For example, you could use this page that you are reading right now.
      2. Click the Ripple icon beside the address bar, then click Enable.
      3. Review and accept the license agreement.
      4. Now when you click the Ripple icon you will be able to click Start Ripple Services. If you want Ripple to start automatically every time you start the Google Chrome browser, select the checkbox below Start Ripple Services.
      5. You can use Disable to stop displaying the current page in the emulator.
  3. In the browser's address bar, type the URL or path to the landing page of your application (typically index.html). For example, try out the kitchen sink sample application at the following URL:
  4. Click the Ripple icon beside the address bar, then click Enable.
  5. If this is the first time you've enabled the Ripple emulator for this particular page, you will need to select the platform that your application is intended for. Select WebWorks. The Ripple emulator remembers this selection and loads it automatically the next time you load the same URL.
  6. If you want to change the platform that you are testing with, under the Platforms panel, click the setting next to Platform, select a platform, and then click Change Platform. Similarly, to change devices within the current platform, use the Devices panel.

Explore the other panels in the Ripple emulator to see the additional settings you can use to test your application.

Now that you've tried a ready-made application using the Ripple emulator, create your own BlackBerry WebWorks application and test it with the Ripple emulator. For more information, see:

Access your project in Ripple

If you do not have a web server set up, you can open files directly from the local file system on your computer by completing the following tasks:

  1. Create a folder named RippleSites in one of the following locations:
    • Windows XP: C:\Documents and Settings\<Username>\RippleSites
    • Windows 7: C:\Users\<Username>\RippleSites
    • Mac OS: /Users/<Username>/RippleSites
  2. Copy your project folder and all of its contents into the RippleSites folder.
  3. In the address bar, type http://localhost:9910/ followed by your project folder and landing page. For example:

In Mac OS, if you have packed and launched your application by using the Package & Launch option in the Ripple emulator, the RippleSites folder is created automatically, however, you may have to change its permissions so that you can copy or move your local resources into it.


The Ripple emulator interface includes a rich set of control panels that enable you to interact with your application as if you are using a mobile device. You can simulate a GPS location, the device accelerometer, device events, and much more.



Devices This panel enables you to quickly switch between the devices that are supported for the selected platform. You can also switch the device orientation from portrait to landscape for devices that support the functionality, so you can test your application layout for various screen sizes and orientations.
Platforms This panel enables you to switch between platforms.
Information This panel provides you with general information about your application, including the current platform and device that are set for the emulator.
Accelerometer This panel enables you to simulate device rotation and movement using a three dimensional device.
Messaging This panel enables you to type simulated SMS messages to send to the device.
Push This panel enables you to use the BlackBerry WebWorks Push API.
Settings This panel enables you to change Ripple-specific settings, such as the theme and tool tips display.
Device & Network Settings This panel is specific to the platform that you are using. You can set communication transports that your application uses, device identifiers such as the IMEI or PIN, and other network settings. You can use various APIs with your application to access these settings.
Geo Location This panel enables you to simulate changes in the physical location of the device, slow down GPS response times, simulate a GPS timeout, and change other GPS simulation settings.
Events This panel enables you to simulate system level events that are supported in the specified platform.
Config This panel displays information about the config.xml file for your application, and includes alerts for errors and omissions in the config.xml file.
Phone This panel enables you to simulate various call states, such as missed or received calls.
Build This panel enables you to specify settings for building, packaging, and signing your application.

Last modified: 2013-10-02