Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Analytics Service

Overview

The Analytics
Service is a component of the BlackBerry
Application Platform that can help you better understand the characteristics of your users and
their behavior. By integrating the Analytics
Service into your application, you can access a wide range
of data that can help your organization make informed business decisions.

Identifying
your users: To help you identify the audience for your application, you can view data
about the BlackBerry device models, BlackBerry Device Software versions, countries of origin, and languages of your users.

Understanding user behavior: To gain a better understanding of how your users use your
application, you can view data about the number of unique users, the total number of
sessions, and the average length of a session.

Tracking
specific actions and events: To identify which parts of your application get the most
use, you can view data about screen views, button clicks, application errors, and
more.

Simple and flexible implementation

The Analytics
Service APIs are designed to be flexible and
easy to implement. Your application can collect and send data about your users (and how they
interact with your application), without you having to add a lot of additional code in your
application. To set up your development environment, you only need to add the Analytics
Service library and a configuration file to your
BlackBerry application
project. After you set up your application, you can configure the application to collect
information about application starts and transitions. If you want to track more specific
actions or events, you can design your application to invoke one of the data collection
methods using only a few lines of code.

Metrics and reports

The parameters that your application sends to the data collection server
populate the metrics and reports that you view in the Analytics
Service web portal. Depending on the needs of
your organization, you can make the metrics and reports as simple or as complex as you want
them to be by manipulating the arguments that you pass into the data collection methods.
Metrics describe high-level information such as the number of screen views, number of unique
users, and the average length of sessions. Reports contain more detailed information about
specific events that occur in your application, such as button clicks, ad views, and errors.
For a complete list of the metrics and reports that are available, see the Analytics
Service Web Portal User Guide at http://docs.blackberry.com/en/developers/subcategories/?userType=21&category=Analytics+Service
.

Application performance

To help minimize the impact that data collection has on the performance of
your application and the BlackBerry device, the Analytics
Service API
includes the following features.

Feature

Description

Thread creation

Data collection processes don't use the main application thread.
When your application collects and sends data to the data collection server, your
application automatically creates a new thread. Creating a separate thread helps
ensure that delays or exceptions that might occur during data collection don't
block the user from interacting with the application UI.

Data queuing

Your application sends the data that it collects to a queue
system. From the queue system, the application sends the data to the data
collection server in fixed intervals. If your application can't send data to the
data collection server (for example, in cases when the device can't connect to the
wireless network), data remains in the queue until the device can send data.

In the configuration file, you can specify how many times the
application should attempt to send data and how much data can be in the queue at
once.

Battery level detection

When the battery level of a device drops below the specified
level, your application stops sending data over the wireless network to the data
collection server. Data is still collected if the battery level drops too low, but
it remains in the event queue until the battery level rises above the specified
level again.

In the configuration file, you can specify the minimum battery
level at which the application can collect and send data.

User identity protection

The Analytics Service is designed to
collect data about user behavior in your applications, without revealing any personal
information about your users. To organize data effectively, the data collection server
requires a unique identifier for each user. To create a unique user ID that doesn't reveal
any personally identifiable information, the application hashes the PIN for the device and
applies Base64 encoding. If the PIN for the device is unavailable, the application creates a
random 32 character string.

Architecture: Analytics
Service framework

Component

Description

Application that integrates the Analytics
Service library

The Analytics
Service library enables your BlackBerry application to send data about user behavior over the wireless
network to the data collection server. Typically, event data includes a number of
different parameters that describe the event, as well as non-identifying
information about user, such as the BlackBerry device model, and the BlackBerry Device Software version.

Data collection server

The data collection server receives event data from your
application, stores the data, and compiles the data in reports web portal for you
to view. For each event that your application sends data about, your application
includes the dcsid parameter, which is a unique
identifier for your application. The data collection server requires the presence
of the dcsid to organize data based on the
application that sends it.

Web portal

The web portal is a UI that you can use to view data about user
behavior in your applications.

Process flow: Collecting, organizing and displaying data about an
application

A user
performs an event that you want to track in your application. For example, a user clicks
the help icon in your application.

The
application invokes the appropriate data collection method. The following code sample
shows an example of how your application can collect data about button clicks.