Nokia Analytics Collector and Analytics API

Nokia Analytics Collector (NAC) implements the Analytics API, providing two classes to support collection of application usage data:

Analytics::Application is a class that represents the client application and provides properties shared between Session instances.

Analytics::Session is a class used to log application-specific events.

Both Analytics::Application and Analytics::Session need to be instantiated by the client application.

Calling Analytics API from QML and C++

The Analytics API can be used from both QML and C++ code.

QML usage example:

  // Import AnalyticsNokia QML plugin.
  import AnalyticsNokia 1.0

  // Initialize Application class and set mandatory properties.
  AnalyticsApplication {
      id: nacApplication
      agentName: "nac-test qml example app"
      agentVersion: "1.0"
  }

  // Initialize Session class and set mandatory properties.
  // AnalyticsSession's agentName property must match
  // AnalyticsApplication's agentName property.
  AnalyticsSession {
      id: nacSession
      sessionId: "nacSession1"
      agentName: "nac-test qml example app"
  }

  // Open a session
  nacSession.open();

  // Log an event
  nacSession.logEvent(AnalyticsSession.ActivityLogEvent, "QML event")

  // Close the session
  nacSession.close(AnalyticsSession.AppExitCloseReason);

C++ usage example:

  // Import AnalyticsNokia header.
  #include <analyticsnokia.h>

  // Initialize Application class and set mandatory properties.
  Analytics::Application nacApplication;
  nacApplication.setAgentName("nac-test c++ example app");
  nacApplication.setAgentVersion("1.0");

  // Initialize Session class and set mandatory properties.
  // Session's agentName property must match with Application's agentName
  // property.
  Analytics::Session nacSession;
  nacSession.setSessionId("nacSession1");
  nacSession.setAgentName("nac-test c++ example app");

  // Open a session
  nacSession.open();

  // Log an event
  nacSession.logEvent(Analytics::Session::ActivityLogEvent, "C++ event")

  // Close the session
  nacSession.close(Analytics::Session::AppExitCloseReason);

Logging events to one session

It is also possible for QML and C++ code to log events into the same session. To do this:

set the properties sessionId and agentName for the Analytics::Session objects to the same values in QML and C++
instantiate the class Analytics::Application only once in C++ or QML code

Linking the client

To link the client application against the Analytics API, add following line in to the client application's project file (.pro):

  LIBS += -lanalyticscollector

Network connections

NAC does not open network connections on its own. Instead, it monitors and uses open connections to send data to the back-end server. For this reason, a connection must be opened by the client application or some other application before analytics data can be dispatched to the server.

MeeGo - Aegis secure storage

On the MeeGo platform, NAC 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 NAC. For more information, please see: https://projects.maemo.org/trac/meego-security/wiki/meego-security-aegis-manifest

S60 - Capabilities

An S60 client application using NAC requires the following Symbian capabilities to be enabled:

NetworkServices
LocalServices
ReadUserData
WriteUserData
UserEnvironment
ReadDeviceData

Note that {ReadDeviceData} cannot be used with self-signed applications. For further information about Symbian capabilities, please see http://wiki.forum.nokia.com/index.php/Capabilities The {ReadDeviceData} cabability requirement comes from Qt Mobility System Information API. See: http://doc.qt.nokia.com/qtmobility-1.0/quickstart.html

S60 - Heap size

In addition, in S60, the default maximum heap size for a Qt application may be insufficient, as the maximum memory consumption for NAC may reach 1500kB. We recommend that you increase the client application's maximum heap size to 33MB by adding following line to its project file (.pro):

  TARGET.EPOCHEAPSIZE = 0x020000 0x2000000

This heap size recommendation comes from Qt.

S60 - Deploying your application

The applications should embed the NAC SIS package into their SIS package and define a dependency to it, e.g.:

  analytics_deployment.pkg_prerules = "@\"NokiaAnalyticsCollector.sis\",(0x20031573)"
  analytics_deployment.pkg_prerules += "(0x20031573), 1, 0, 0 ~ *, *, *, {\"NokiaAnalyticsCollector\"}"
  DEPLOYMENT += analytics_deployment

In addition, NAC needs Qt 4.7.3 and Qt Mobility 1.1.3 to work properly, so the applications have to use Smart Installer to get these. In short, you need to provide an installer sis which contains your application sis (embedding NAC) and a Smart Installer sis. For more details see http://wiki.forum.nokia.com/index.php/Nokia_Smart_Installer_for_Symbian