Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Analytics SDK extension Information

End of Life Notice

The BlackBerry Analytics service that this extension depends on will be disctontinued on November 30th, 2013. At that time, the data captured by the service will no longer be accessible through the WebTrends portal. Applications will also stop reporting data to the service.

If you desire a replacement service, it is recommended to use the free Flurry service for HTML5/JS applications.

The BlackBerry Analytics SDK allows you to quickly capture analytics data from your applications and review this aggregate data about your user base in the Analytics Portal.

Register for the SDK here: http://us.blackberry.com/developers/platform/analyticsservice/

View documentation on the Portal here: http://docs.blackberry.com/en/developers/subcategories/?userType=21&category=Analytics+Service

Authors: Tim Windsor

Known Issues

  • None

Tested On

  • BlackBerry Torch 9810 v7.1.0.213

Requires BlackBerry WebWorks SDK for Smartphones v2.0 or higher

Have a problem with this extension? Log an Issue or contact the Authors

How To Configure The Extension For Use

  1. Locate your BlackBerry WebWorks SDK for Smartphone extensions directory using your File Explorer. Default path is C:\Program Files\Research In Motion\BlackBerry WebWorks Packager\ext

  2. Create a new webworks.analytics directory in the ext directory

  3. Download the source from this repository and unzip it to a location on your computer

  4. Using File Explorer browse to this extension's downloaded source code Smartphone\Analytics

  5. Copy the library.xml file from the downloaded Smartphone\Analytics directory to your new ext\webworks.analytics directory

  6. Copy the downloaded Smartphone\Analytics\src\webworks directory to your new ext\webworks.analytics\webworks directory

NOTE: Be sure to back-up this ext\webworks.analytics directory in your WebWorks SDK extensions directory before performing a WebWorks SDK upgrade. Simply copy it back into the ext directory after you have completed your SDK upgrade.

Required Feature ID

Whenever you use the below feature id in any of your WebWorks applications this extension will be loaded for use.

<feature id="webworks.analytics" />

Capturing the application events in Analytics is important and requires the use of the BlackBerry.app Feature:

<feature id="blackberry.app.event" />

How to add the Extension to your app

REQUIRED: Visit http://us.blackberry.com/developers/platform/analyticsservice/ to register and for more details of the SDK. DCSID is provided by the Analytics SDK, when you register a space.

Put a Script like this in your head element:

<script type="text/javascript">
	function onBackgroundCallback() {
	function onForegroundCallback() {
	function onExitCallback() {
	// The dcs id is a value you will get from the Analytics Portal when you create a Space for your app. 
// This is a test id.
	// second parameter is app category
	webworks.analytics.register('dcsgkyqzl6bv0h08zoc7zofva_4h6y', 'Utilities');

After that, call methods like the following to track events in your app:

Track when a user clicks on an ad:

	webworks.analytics.adclick(/mainscreen', 'Main Screen', 'adclick', 'Demo Ad')

Track when users have been shown ads:

webworks.analytics.adimpression('/mainscreen', 'Main Screen', 'adimpression', 'Demo Ad1', 'Demo Ad2')

Track when a button has been clicked in the app (does a feature get used? do users find this button?):

webworks.analytics.button('/mainscreen', 'Main Screen', 'upgradebutton')

Track conversions/purchases in your app:

	webworks.analytics.conversion('/mainscreen/upgrade', 'Main Screen', 'upgrade', 'main app content', 'upgrade to full version')

Track anything not covered in another method:

	webworks.analytics.custom('/mainscreen', 'Custom', 'custom event')

Track media playback:

	webworks.analytics.media('/mainscreen/videoplay', 'Main Screen', 'media', 'Sports', 'tennis.mp4', 'video', 'p')

Track views of a product:

	webworks.analytics.product('/mainscreen/product', 'Product Screen', 'productview', 'Sports', '12345', 'SKU0001')

Track loading of pages/screens:

	webworks.analytics.screen('/mainscreen', 'Main Screen', 'mainscreen view', 'main app content')

Track search queries in the app:

	webworks.analytics.search('/mainscreen/search', 'Searc Screen', 'QueryString', '10')

Track errors:

	webworks.analytics.error('Error Message')
  • The first parameter for most methods is the hierarchical location within the app, such as the screen or page where the event occurs.
  • The second parameter for most methods is the name of the screen where the event occurs.
  • See the JavaDocs for the extension or the Analytics SDK JavaDoc for further details of the parameters.


  1. What happens out of coverage? The library will queue events and send when in coverage. The queue is quite large, but if the queue overflows, events will be dropped.

  2. What is the longest string I can send? The strings are essentially unlimited, but it is recommended to keep them as short as possible. Longer strings will require more data and battery to transmit, and they will be of limited use in the portal. The point of Analytics is really to count events over time, not send a lot of detailed data.

  3. What is the JAR file "AnalyticsService_v1.0.jar"? This JAR is the BlackBerry Analytics Service SDK. The extension is really a wrapper for the Java SDK that is in this JAR file. The JAR file needs to be included to make the extension work so it's included here in the proper place and with the proper version. If the Analytics SDK changes in the future, the extension may require updating and would need to be updated at the same time with the new JAR file. This JAR file is closed source, but free to use. It is typically accessed by downloading the SDK from the Analytics Portal, but in order to simplify deployment of this extension, it's been included here.