Integrating Usage Intelligence with Server Applications

Providers of on-premise server applications can fully benefit from the advanced usage analytics provided by the Usage Intelligence solution. The implementation will depend on the type of application, and whether you are interested in tracking aggregate product usage by server installation or if you would like to track the individual users using your application.

In this article, we will go over the implementation options for server applications and outline the benefits of each to help you decide which one is best for you.

NOTE: Code examples in this article use the Usage Intelligence .NET SDK. We also offer SDKs for Java, C/C++ and Objective-C.

Option 1 – Track Aggregate Usage Per Server Installation

This option is suitable if you want to collect aggregate usage data from different companies or on-premise server installations, rather than focusing on individual users who access your server application from their browser or desktop client. When choosing this option, the Usage Intelligence SDK is configured to operate in multi-session mode and your application must manage when a user session starts and stops. This typically means that a session is started when a user logs in and it is stopped when a user logs out. In terms of integrating the SDK into your server application you would perform the following steps.

To track aggregate usage per server installation:

Create the Usage Intelligence SDK instance:

bool defaultReachOut = false;
string ruiPath = "<Path to Usage Intelligence DLLs>";
RUISDK rui = new RUISDK(defaultReachOut, ruiPath);

Create the SDK configuration with multi-session enabled:

string filePath = "<Path were SDK config files will be saved>";
string productID = "<My Product ID>";
string appName = "<MyAppName>";
string productUrl = "<My Product URL>";
string aesHexKey = "<My AES Key>";
int ruiProtocol = (int)RUIProtocolType.httpPlusEncryption;
bool multiSession = true;
bool autoReachOut = false;
 
rui.CreateConfig(filePath, productID, appName, productUrl, ruiProtocol, 
aesHexKey, multiSession, autoReachOut);

When the application starts also start the SDK:
```
rui.StartSDK();
```

For each user that logs in start a session and specify a unique session ID:

string sessionID_User1 = "<Unique session ID>";
rui.StartSession(sessionID_User1);

When tracking events specify the relevant session ID for the user generating the event:

string eventCategory = "My Category";
string eventName = "My Event";
rui.TrackEvent(eventCategory, eventName, sessionID_User1);

Once a user logs out or their session is terminated stop the session with the corresponding
session ID:
```
rui.StopSession(sessionID_User1);
```
When the application is stopped also stop the SDK:
```
rui.StopSDK(0);
```

The value of this type of implementation is that performance and distribution metrics will reflect your customer base and the number of server applications they have installed. For example, if you have two companies ABC and XYZ which both have a single installation and 100 users each logging in to your application, the Usage Intelligence Dashboard will show statistics based on two installations, but the usage data from each of those two installations would reflect activity from the 200 users that are connected to those servers.

When analyzing data you can compare user behavior across companies or sites. To achieve this, you can make use of a custom property to identify specific companies/sites and setting this in your application after creating the SDK configuration. If you prefer that the data remains anonymous you can use the Client ID to filter and segment data by installation. This will allow you to filter data by a specific company/installation only, or compare data between different companies.

In the example below, a distribution report shows the OS Version for companies ABC and XYZ, where each of these have a single server installation.

If you go for this implementation option, event counts will reflect the total number of events generated by users for all installations. When looking at Basic Event Tracking statistics you must keep in mind that average event counts will be based on the number of server applications installed and not individual users. For example, if users at company ABC generated an event 100 times while users at company XYZ generated the same event 50 times, the total number of times that event was generated will be 150 with an average of 75 events per installation.

To summarize:

Product performance and distribution metrics will be based on number of application installs.
Event counts per user represent the aggregate number of events generated per installation.
Each application install can be associated with a company by using a custom property or anonymously group data per install by using the Client ID.

Option 2 – Track Individual Users

If tracking individual users is important to you then you can implement the Usage Intelligence SDK in a way that simulates the different users which log in to your application. This option is suitable when you care more about the number of users using each installation and their individual usage and less about the number of server applications installed.

If you choose this option, each user must have a different configuration path associated with it and a Usage Intelligence SDK instance is created each time a user logs in to the application. This means that when integrating the SDK your application would do the following every time a user logs in.

To track individual users:

Create a Usage Intelligence SDK instance:

bool defaultReachOut = false;
string ruiPath = "<Path to Usage Intelligence DLLs>";
RUISDK rui = new RUISDK(defaultReachOut, ruiPath);

Check if the user has a folder associated with it, if not create one.

Create the SDK configuration with this folder and multi-session set to disabled so that a session will be automatically started once the SDK is started:

string userPath = "<Path where SDK config files will be saved for this user>";
string productID = "<My Product ID>";
string appName = "<MyAppName>";
string productUrl = "<My Product URL>";
string aesHexKey = "<My AES Key>";
int ruiProtocol = (int)RUIProtocolType.httpPlusEncryption;
bool multiSession = false;
bool autoReachOut = false;
 
rui.CreateConfig(userPath, productID, appName, productUrl, ruiProtocol,
aesHexKey, multiSession, autoReachOut);

Start the SDK:
```
rui.StartSDK();
```

When tracking events do not specify a session ID:

string eventCategory = "My Category";
string eventName = "My Event";
rui.TrackEvent(eventCategory, eventName, "");

Once a user logs out or their session is terminated stop the SDK instance. The session that was started automatically will also be stopped:
```
rui.StopSDK(0);
```

When using this option, performance and distribution metrics in the Dashboard will reflect the number of individual users making use of your application, rather than the number of application installations. Therefore if companies ABC and XYZ both have a single installation and they each have 100 users logging in to your application, the Usage Intelligence Dashboard will show statistics based on 200 users.

To identify which users belong to a specific company, you can use a custom property to associate a user with a company and in your application set this for each user after creating the SDK configuration. If you want the data to remain anonymous you can use the Machine ID to filter and segment data by installation.

In the example below, an Event Usage Frequency report compares event usage of two events between companies ABC and XYZ. The actual report is showing the unique users that have connected to each company’s server and used the specific tracked events.

To summarize:

Product performance and distribution metrics will be based on the number of users logging in your application at each install.
Event counts per user represent the number of users using the application across all installations.
Each application install can be associated with a company by using a custom property or anonymously group data per install by using the Machine ID.

We suggest you take a look at the Usage Intelligence dashboard to get a better understanding of the analytics data and reports available. You can sign up for an account to get access to our DEMO Product or start a free trial to experiment with your own test product. If you need further assistance to help you decide which implementation option is best for you, get in touch with us and we would be happy to discuss your use case.

Integrating Usage Intelligence with Server Applications