In-App Analytics API library

Introduction

In-App Analytics is a system that provides a configurable data tracking and delivery mechanism to allow application developers to monitor how their applications are used, and ultimately to help them deliver the optimal user experience.

The system includes:

In-App Analytics API - a developer resource implemented in the In-App Analytics Library; the API provides a set of interfaces necessary for applications to be able to collect and submit usage data to a back-end server
In-App Analytics Server - the back-end server that receives and processes usage data from applications, generating application usage reports that can be accessed through its Web interface.

After you have integrated the application with the In-App Analytics Library:

The application logs the events containing usage data, using the In-App Analytics API to cache them locally
When a sufficient number of events has been collected to build a batch, the Analytics Library sends the batch to the In-App Analytics Server (provided that a network connection is available)
The In-App Analytics server processes the received data and generates user-friendly reports, making them accessible through its Web interface

List of classes

Name	Usage
DeclarativeAnalytics	Used for Qt/QML development
Analytics	Used for Qt/C++ development

Key use cases

By logging application usage data you get information of the users and how they utilize the application. With that knowledge, you can:

enhance the user experience of the application
prioritize feature development
optimize product offering
identify advertising opportunities

Types of reports

The In-App Analytics Server generates the following types of standard reports on the basis of the usage data that applications submit through the In-App Analytics API:

Usage summary - total number of users and sessions, new users, average session length, and so on
Geographic view - reports grouped by country allow you to discover where the users are and where the application is used the most
Operator view - reports grouped by carrier
Device view - reports grouped by device type
Users view - reports grouped by user
Screens view - reports grouped by application screen (application view)
Actions view - reports grouped by action performed by users in the application
Sessions view - reports that show session start-up, shut-down and length
Version view - reports grouped by application version

In addition, you can collect custom reports on specific actions.

Getting Started

Get the application key

To use the In-App Analytics Library, you need to obtain the application key for your application. Follow these steps:

1. Log in to the In-App Analytics Web site at https://nokia.motally.com/login.php

2. Click on "Add App" in the navigation panel on the left

3. Fill in the details for your application and click "Done" - the table "App" now displays your application key

4. Use the application key to initialize the API

Set up the development project

Fetch libinappanalytics and libinappanalytics-dev packages from the repository and add them to the dependencies of your project.

Aegis secure storage

In-App Analytics relies on the Aegis secure storage for protecting the data from unauthorized access on the device. Applications should enable Aegis secure storage by including an Aegis manifest, although no specific credentials are needed by In-App Analytics. See Harmattan security section for more information.

Privacy considerations

The In-App Analytics Library creates a persistent randomized user ID for every application and no personally identifiable information is collected. All the information on the server side is kept only at the aggregated level that can be seen from the Web interface (https://nokia.motally.com). If the data is stored in a cache on the device for more than six months (that is, if the application is not used with an open data connection), the In-App Analytics Library deletes the data without sending it to the server.

Opt-out

As a developer, make sure that the application users are aware of the secondary purpose of data collection which is usage logging. Consider including advice in the application terms and conditions. However, in addition, the application needs to offer end users a possibility to opt-out from data collection.

Database storage

The In-App Analytics Library uses a local database file to store collected events (usage data) until they have been sent to the back-end server. The database file is located in the private folder of the application, and thus the application must not use any file names beginning with "analytics-".

The maximum size of the database file is limited to 512 kB. When it becomes full, data collection is suspended until the collected events have been successfully submitted to the back-end server.

The In-App Analytics Library does not open a data connection to the back-end server by itself, but uses any available open connection to dispatch the accumulated data.

When a data connection is open and the In-App Analytics API has been initialized, it checks whether there are enough events or events from closed sessions stored in local cache to be sent to the back-end server. The minimum number of events to be cached before dispatch to the server can be controlled by the developer. Also the connection type can be controlled.

To save battery life, In-App Analytics Library does not send the data to the server if battery level is below 10%.

Example of the In-App Analytics QML API usage

Calling In-App Analytics API from QML

The example below demonstrates how to call the In-App Analytics API from QML. The code:

defines an instance of the Analytics element (Item)
sets its properties
initializes and starts In-App Analytics
logs events
closes In-App Analytics

 import Qt 4.7

 // Import Analytics QML-plugin
 import Analytics 1.0

 // Create a QML Item AnalyticsQ and set values for all available optional properties.
 Analytics {
     id: analyticsExample
     connectionTypePreference: Analytics.AnyConnection  // optional
     appLanguage: "Fi"                                  // optional
     minBundleSize: 20                                  // optional
     loggingEnabled: true                               // optional
 }

 // Initialize item with \e {Application key} and \e {Agent name} values.
 analyticsExample.initialize("someAppKey", "someAppVersion");

 // Start gathering analytics events (associated with a certain screen or app
 // view).
 analyticsExample.start("someScreen");

 // Log error event associated with the given screen (app view).
 analyticsExample.logEvent("someScreen", "errorEvent", Analytics.ErrorLogEvent);

 // Log activity event with the given screen.
 analyticsExample.logEvent("someScreen", "activityEvent", Analytics.ActivityLogEvent);

 // Stop gathering analytics events => subsequent "logEvent" calls won't be registered.
 analyticsExample.stop("someScreen", Analytics.AppExit);