Upsight logo Back to top

Enterprise Android

Quick Start Guide

The Basics


Before You Start

Although the Android SDK is built on top of our Data Collection API, we encourage you to use the SDK over the Data Collection API directly. Using the SDK ensures consistency in how metrics are calculated (i.e. the SDK sends a pgr message every 30 seconds to calculate session duration) and ensures all data gets sent to the Upsight Analytics servers, even with the intermittent activity (i.e. offline play) that occurs with mobile use.

The Upsight Enterprise Android SDK currently supports API Level 10+. Older versions of Android are not supported.

Download SDK

Things To Keep In Mind

  • The Upsight Analytics Android SDK supports Android API level 10 or higher (Android 2.3.3 and above).
  • For referral tracking, the com.android.vending.INSTALL_REFERRER is required.
  • For attribution through third parties, adding Google Play Services to your application is required.
  • At startup, the SDK spawns 2 threads:
    • NetworkManager – this thread tests connectivity once every minute.
    • OnlineQueue – this thread sends messages to the API servers in the background.

Step 1

Add android.permission.INTERNET, android.permission.ACCESS_WIFI_STATE, and android.permission.ACCESS_NETWORK_STATE permissions in your AndroidManifest.xml.

Step 2

Download and add the latest Android SDK to your build path. For ADT/SDK versions 17 and later, it must be placed into the libs folder.

Step 3

If you plan on using a third party attribution service, add Google Play Services to your application as described in Google's official developer documentation.

Step 4

Add the following lines of code to your main activity onResume method. Replace API_KEY with your application’s Upsight Analytics API Key. If you would like to enable SDK logging, you must enable debugging mode:

@Override 
public void onResume() { 
super.onResume(); 
Kontagent.enableDebug(); //add this line to enable debugging 
Kontagent.startSession("API_KEY", this, Kontagent.TEST_MODE);  
}

Important If you are using the Enterprise and regular SDKs, make sure to call the startSession method before making an OpenRequest Open Call.

Considerations

  • The SDK automatically generates sender IDs on initial application launch. However, you may override this.
  • Unless you have sendApplicationAdded set to false in startSession, applicationAdded will be called upon initial application launch.
  • The Android SDK methods mirror the Upsight Analytics Mobile Data Collection API.
  • The Android SDK manages data when the device is both offline and online.
  • Messages to API servers are capped at 10 requests/second. They are made by a low priority thread to minimize device performance overhead.
  • Messages are written to device storage if offline.

Create QA and Production Apps

Login to your Upsight account and create 2 application instances. Create one application instance for QA and one for Production, naming them similar to the following:

  • MyApp_Name - QA
  • MyApp_NAME - Production

Each of these application instances have a unique API key, which is automatically generated when the application is created. Make note of this API key, as you must specify this key when instrumenting your application. The API key you specify also determines which application instance on the Upsight servers your data is sent to. During the QA phase, you will want to direct your data to your QA application instance by specifying the QA application API key in your calls. Once you go live, change your calls to use your Production API key to send data to your production application instance.

Test Your Instrumentation

During the instrumentation phase, direct your application to send data to our Test Server. To send data to the Test Server, simply point all API calls to the Test Server in the startSession method:

Kontagent.startSession("<QA_API_KEY>", this, Kontagent.TEST_MODE);

The parameter mode defines what server you will be sending data to: Test or Production.

To stop a session, call the following:

Kontagent.stopSession();

The stopSession method will also save all outstanding messages to device storage before session shutdown.

SDK Logging

If you would like to enable/disable SDK logging, include the appropriate line of code from the following:

Kontagent.enableDebug();
Kontagent.disableDebug();

View and QA Your Test Data

Once you have validated your instrumentation with our Test Server and would like to view your test data, you must send this data to our Production Server. Change the last parameter in startSession to send data to the Production Server:

Kontagent.startSession("<QA_API_KEY>", this, Kontagent.PRODUCTION_MODE);

You can now view your data (by clicking on MyApp - QA in the Test Server) in the Upsight Analytics Dashboard.

On the Test Server, you should see 3 message types highlighted in green:

  • Application Added
  • Page Request
  • Event

The Application Added message sends when a user first installs your instrumented application. You should have one per user install.

The Page Request message sends about twice a minute while the application is running. It tells the server that your app is open.

Custom Event messages can contain any type of information, but this particular custom event message is the fingerprint message used for identifying the application.

Once data is sent, you can also run integration reports and receive immediate feedback on the validity of your instrumentation. For example, the Integration Reports tool can be used to generate a QA of your API calls. Using these tools to validate your instrumentation will help ensure data integrity when data is sent to our production servers. Please note, you should be using your QA API key when testing your non-production instrumentation.

Send Your Production Data to Upsight Analytics

During the testing of your instrumentation, you should have been using your QA application (MyApp - QA). When you are ready to send data to our production servers to view in your production application instance (MyApp - Production), simply change the parameters in startSession to point to the Production Server and production application:

Kontagent.startSession("<PROD_API_KEY>", this, Kontagent.PRODUCTION_MODE)

From this point on, you are live, and Upsight will update your data on an hourly basis. To view your production data, click on MyApp - Production in the Upsight Analytics Dashboard.

As the Android SDK is built on top of our Data Collection API, all required and optional parameters, as well as any constraints, are synonymous with the Data Collection API specification.

The following examples show instrumentation of a customEvent call with no optional parameters passed:

Kontagent.customEvent("eventName", null);

Capturing Device Information

By default, requests are sent to the Upsight Analytics Test Server. To send requests to the Production Server, change the last parameter in startSession to Kontagent.PRODUCTION_MODE. As you will have set up separate applications for testing and production, make sure to use the correct application API Key when sending data to the Test or Production Servers.

After the first startSession call, you should immediately send the sendDeviceInformation call. Refer to the Basic Basic Android Methods and Advanced Android Methods sections below for more information and code examples.

Basic Android Methods

MethodDescription
HashMapWhen a method accepts optional parameters, they must be sent as a HashMap.
startSessionCall this method to initiate the SDK.
stopSessionCall this method to close the session. No parameters are required.
sendDeviceInformationThis method gathers carrier information and OS version when invoked. This method should be called upon every launch.

Advanced Android Methods

MethodDescription
applicationAddedCall this method if applicationAdded is called.
customEventSend this API call when a user performs an action specific to your application.
revenueTrackingThis call provides information for tracking revenue and monetization transactions by users.

How much does the Upsight Analytics SDK add to my app size?

The Upsight Analytics Android SDK typically adds around 100 KB to the final app size.

How many messages are buffered when the device is offline?

By default the queue size is 499 APIs. When the queue is full, new APIs added to the queue will be dropped. You can change the size of the queue with the following function:

Kontagent.changeMaxQueueSizeForSessionApiKey(newQueueSize, apiKey);

Quick Start Guide

Android Mobile Acquisition Tracking


Setting Permissions

Please make sure you have the following permissions added to your AndroidManifest.xml.

<uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>

and

<uses-permission android:name="android.permission.INTERNET"></uses-permission>

Referrer Tracking

Implementing Android's Broadcast Receiver Method enables you to track the effectiveness of your marketing dollars by source, channel and other parameters passed through the referrer string of a tracking URL. These referrer parameters are passed from ad-click to the Android App Store (Google Play/Amazon, etc.). Upon application download, the broadcast receiver grabs specific referrer parameters in the URL string to attribute the install to the originating click.

Register the KAnalyticsReceiver receipt as a new BroadcastReceiver in your AndroidManifest.xml

The following BroadcastReceiver allows your app to respond to the INSTALL_REFERRER intent broadcast by the Google Play Store when your app is installed. Add it to your AndroidManifest.xml file as the following example does:

<!-- Used for install referral measurement-->
<receiver android:name="com.kontagent.KAnalyticsReceiver" android:exported="true">
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

Note You need to implement the below logic only if your application has more than one broadcast receiver registered to handle the INSTALL_REFERRER intent.

If the KAnalyticsReceiver is implemented, but another receiver is receiving the INSTALL_REFERRER instead, your application has more than one broadcast receiver registered to handle the INSTALL_REFERRER intent. If your application has two receivers registered for this intent, it is recommended that you create a custom receiver that can receiver the INSTALL_REFERRER intent and dispatch it to other receivers, including the KAnalyticsReceiver receiver, as necessary. Here is an exmaple of a sample receiver to accomplish this:

package com.example.testerapp;

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
/*
 *  A simple Broadcast Receiver to receive an INSTALL_REFERRER
 *  intent and pass it to other receivers, including
 *  the Kontagents Analytics receiver.
 */
public class ClientReceiver extends BroadcastReceiver {
  @Override
  public void onReceive(Context context, Intent intent) {
    // Pass the intent to other receivers.
    // When you're done, pass the intent to the Kontagent Analytics receiver.
    new KAnalyticsReceiver().onReceive(context, intent);
  }
}

MAT Test Server Validation

To validate that you have enabled MAT, compile your test build in your selected IDE and run the project. You should see an APA install message fire on start session. The su tag of the APA will have 9 device ID hash permutations (as seen in the image below). If your device happens to have an IMEI value, we will also capture this. In that case there will be 16 values in the su array.

This is to ensure that when we receive an incoming device ID from an external source, we are able to match and attribute at least one value in the su array from click-to-install.

Basic Messages

HashMap


Overview

When a method accepts optional parameters, they must be sent as a HashMap.

Required Parameters

Optional Parameters

Code Example

Any examples with a params object assumes that a HashMap has already been declared like in the following example:

Map<String, String> params = new HashMap<String, String>();

Add optional params by using the put method:

params.put(<param>, <value>);

Clear your HashMap by using the clear method:

params.clear();

Basic Messages

startSession


Overview

Call this method to initiate the SDK. An apa message will be sent on first run.

Note The Enterprise SDK creates a user identifier, referred to as the sender ID. This ID can be substituted with another identifier (i.e. Your own ID). When substituting with another identifier, ensure that it is an integer, otherwise it will not pass.

Warning Using a custom sender ID instead of the one generated by the SDK can result in potential drawbacks for marketing and analytics. For further information, please contact your CSM or Upsight Support.

Required Parameters

Parameter Type Description
ApiKeystring The API Key of your application. This key is automatically generated when you set up your application in your Dashboard.
modestring Determines whether you send data to Upsight Analytics Test or Production servers. For Production, set this parameter to: Kontagent.PRODUCTION_MODE. For Test, set this parameter to: Kontagent.TEST_MODE.

Optional Parameters

Parameter Type Description
senderIDunsigned 64-bit int A unique, unsigned 64-bit integer in the form of an NSString. This parameter denotes the unique identifier of the application user. If your application creates user IDs larger than 64-bits, you must convert the user ID to an unsigned 64-bit integer to send to Upsight Analytics. For more information click here.

Code Example

Start a session. The SDK generates a user ID automatically.

Kontagent.startSesssion("<apikey>", <context>, <SDK_MODE>);

Start a session by specifying your own user ID. This ID will be used in all sent messages.

Kontagent.startSesssion("<apikey>", <context>, <SDK_MODE>, "<sender_id>");

Start a session without sending "Application Added" on first run.

Kontagent.startSession("<apikey>", <context>, <SDK_MODE>, false);

Start a session without sending "Application Added" on first run AND with specifying your own user ID.

Kontagent.startSession("<apikey>", <context>, <SDK_MODE>, "<sender_id>", false);

Basic Messages

stopSession


Overview

Call this method to close the session. No parameters are required.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.

Code Example

When the application loses focus, you should call this to write all unsent calls to disk.

Kontagent.stopSession();

Basic Messages

sendDeviceInformation


Overview

This method gathers manufacturer, model, OS version, and carrier on launch of the application. You should call this method upon every launch.

Required Parameters

No required parameters.

Optional Parameters

Parameter Type Description
v_majstring Major version number. This represents your version number scheme, and is limited to 50 characters. Valid characters are a-z, A-Z, 0-9, -, ., and _.
datastring A JSON object string that is not base64 encoded.

Code Example

Kontagent.sendDeviceInformation(null);

params.put("v_maj", "1.2.3");

Kontagent.sendDeviceInformation(params);

Advanced Messages

applicationAdded


Overview

Call this method if startSession is called, and sendApplicationAdded is set to false.

The presence of a unique tracking tag u or short tracking tag su is used to determine installation source.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.

Code Example

Kontagent.applicationAdded();

Advanced Messages

createSession


Overview

Call this method to create a Kontagent object. Use this method if you wish to send to multiple API Keys.

To put a KontagentSession into TEST mode, use the setMode function.

Required Parameters

Parameter Type Description
contextcontext Context is required for internal Database support.
apiKeystring The API Key of your application. This key is automatically generated when you set up your application in your Dashboard.

Optional Parameters

Parameter Type Description
senderIDunsigned 64-bit int Unique long value in the form of String. By default UID will be generated within SDK.
sdkModestringPRODUCTION or TEST (ISession.KONTAGENT_SDK_MODE_PRODUCTION / ISession.KONTAGENT_SDK_MODE_TEST)
sendApplicationAddedBOOL When TRUE - applicationAdded request will be sent automatically from start method of ISession object.

Code Example

You need to know your API Key. The senderID can be nil, the Kontagent library will fill this in for you.

ISession session = Kontagent.createSession(this, API_KEY, sender_id,
ISession.KONTAGENT_SDK_MODE_PRODUCTION);

Start the Kontagent session.

session.start();

Advanced Messages

customEvent


Overview

Send this API call when a user performs a specific action in your application. This action can be anything that you deem valuable to track, such as the sale of a specific item, or progression to another level in a game.

Required Parameters

Parameter Type Description
namestring The event name, up to 31 characters long, describing the event. Valid characters are a-z, A-Z, 0-9, -, and _.

Optional Parameters

Parameter Type Description
vsigned int An arbitrary value you assign to associate with the event. The default value is 0.
lunsigned 8-bit int A level value can be associated to an action to indicate what game level the user is on. It is possible to view aggregate event counts by level. The level must always be a positive integer in the range from 0 to 255. The default value is 0
st1string An alpha-numeric label, up to 31 characters long, to categorize the event. The characters - and _ are also valid. Not optional if st2 is used.
st2string An alpha-numeric label, up to 31 characters long, to categorize the event. The characters - and _ are also valid. Not optional if st3 is used.
st3string An alpha-numeric label, up to 31 characters long, to categorize the event. The characters - and _ are also valid.
datastring Additional data, a JSON object string representing a dictionary or map of key-value pairs. Click here for more information.

Code Example

Kontagent.customEvent(<event name>, null);

params.put("st1", <subtype1>);
params.put("st2", <subtype2>);
params.put("st3", <subtype3>);
params.put("l", <level>);
params.put("v", <value>);
params.put("data", <data>);

Kontagent.customEvent(<eventname>, params);

Advanced Messages

revenueTracking


Overview

This message provides information for tracking revenue and monetization transactions by users.

Note If you are funnelling your data from the Upsight SDK into the Upsight Analytics Dashboard, do not send both Monetization messages through the Upsight Enterprise SDK and In-App Purchase Tracking through the Upsight SDK. Doing so will cause double-counting in your purchase data. To ensure your purchase data is accurate, if you are using both the Upsight SDK and the Upsight Enterprise SDK, only send in-app purchase tracking through the Upsight SDK, not both.

Required Parameters

Parameter Type Description
vint The revenue value in cents. All values must be passed in cents, and not dollars. Example: $1.25 should be passed as 125. The maximum value that can be passed is 1000000 ($10,000).

Optional Parameters

Parameter Type Description
datastring Additional data, a JSON object string representing a dictionary or map of key-value pairs. Click here for more information.

Code Example

Send a monetization message with no type.

Kontagent.revenueTracking(itemPrice, null);

Send a monetization message with a data object.

Kontagent.revenueTracking(itemPrice, params);

Advanced Messages

setSecureHttpConnectionEnabled


Overview

This message enables or disables Secure HTTP connection (HTTPS). Even though messages are sent asynchronously, messages sent will respect the Secure HTTP connection setting that is set at the time the message is called.

Note The option to use HTTPS must be enabled on the Upsight servers before HTTPS is enabled on the SDK. If this message is sent before HTTPS is activated on the servers, the option may be overridden on the server side even if the user activates this method. Please contact your CSM to enable this option.

Required Parameters

ParameterTypeDescription
isEnabledbooleanDetermines whether to send messages to Upsight Analytics through HTTP or HTTPS.

Optional Parameters

No optional parameters.

Code Example

Enable Secure HTTP Connection

Kontagent.setSecureHttpConnectionEnabled(true);

Disable Secure HTTP Connection

Kontagent.setSecureHttpConnectionEnabled(false);

Advanced Messages

isSecureHttpConnectionEnabled


Overview

This message determines if Secure HTTP connection (HTTPS) is enabled or disabled.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.

Code Example

Return TRUE if HTTPS is enabled, FALSE if HTTPS is disabled.

Kontagent.isSecureHttpConnectionEnabled();

Advanced Messages

startHeartbeatTimer


Overview

Starts the session heartbeat if it is not already started. The heartbeat tracks session duration.

The session heartbeat is automatically started in startSession and automatically stopped in stopSession. Use this method if you wish to reduce the amount of heartbeat messages sent by manually starting and stopping the heartbeat. You can stop the heartbeat by calling stopHeartbeatTimer.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.

Code Example

Kontagent.startHeartbeatTimer();

Advanced Messages

stopHeartbeatTimer


Overview

Stops the session heartbeat if it is not already stopped. The heartbeat tracks session duration.

The session heartbeat is automatically started in startSession and automatically stopped in stopSession. Use this method if you wish to reduce the amount of heartbeat messages sent by manually starting and stopping the heartbeat. You can start the heartbeat by calling startHeartbeatTimer.

Required Parameters

No required parameters.

Optional Parameters

No optional parameters.

Code Example

Kontagent.stopHeartbeatTimer();

Helper Methods

getSenderID


Get Sender ID Method

This method retrieves current session's sender ID value.

Important This function returns a sender ID or null if session hasn't been yet started.

Required Parameters

Parameter Type Description
apiKeystring The API Key of your application. This key is automatically generated when you set up your application in your Dashboard.

Optional Parameters

N/A

Code Example

String senderID = getSenderId("apiKey");