Upsight logo Back to top

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);

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>

Android Mobile Acquisition Tracking

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);
  }
}

Android Mobile Acquisition Tracking

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.