Upsight logo Back to top

Getting Started


Click to view Javadocs.

Basic Integration

The Upsight Android SDK (Software Development Kit) is a set of libraries which enables the use of the Upsight analytics data platform and marketing tools. The SDK architecture combines ease of use while allowing for extensions to be built that can leverage analytics data for advanced usage.

Integrating Upsight's Android's SDK is as simple as 3 easy steps.

The first step is to add the Upsight repository to your application's build.gradle.

allprojects {
    repositories {
        maven {
            url ""

To include all the standard Upsight modules, simply add:

api ''

You may optionally add each dependency as appropriate to your application instead of including all of them. Please see the Advanced Integration section for more information.

The next step is to add the following in your application Manifest. The application token and public key are provided on the Upsight Dashboard under Settings > Applications > "YOUR_APPLICATION_NAME".


    <!-- Application token and public key from Upsight Dashboard -->
        android:value="UPSIGHT_APPLICATION_TOKEN" />
        android:value="UPSIGHT_PUBLIC_KEY" />

    <!-- e.g. android:authorities="com.yourCompany.yourApplication.upsight" -->
        android:exported="false" />

In order to access any API from the SDK, the application needs to build an UpsightContext. This should be done in the onCreate() of your Application or Activity, so we begin tracking the session appropriately:

public class SampleActivity extends Activity {

    private UpsightContext mUpsight;

    protected void onCreate(Bundle savedInstanceState) {
        // Create an UpsightContext from any Android Context.
        mUpsight = Upsight.createContext(this);

If you wish to enable logging, add the following:

mUpsight.getLogger().setLogLevel(Upsight.LOG_TAG, EnumSet.allOf(UpsightLogger.Level.class));

Tip: You may call Upsight.createContext(android.content.Context) anywhere in your application, and as often as you need a reference to UpsightContext. The same instance will be returned on each call.

Tip: You can use UpsightContext anywhere in your application where you currently use an android.content.Context. It provides extra functionality made available by the Upsight SDK.

Advanced Integration

Modular Dependencies

The Upsight Android SDK is modular, so instead of including, you can selectively add each dependency as appropriate to your application:

api ''             // To use the Analytics module.
api ''             // To use the Marketing module.
api ''     // To use the Managed Variables module.
api '' // To use the Google Advertising ID module.
api ''  // To use the Google Push Services module.
api ''           // To use the Marketplace module.

Advanced Integration

Google Play Services

The Google modules automatically pulls in the necessary dependencies from the Google Play Services Client Library 10.2.1. If you wish to manually include a specific version of that library, the Google modules should be added with their appropriate exclude statements instead:

api ('') {
    exclude group: '', module: 'play-services-ads'
api ('') {
    exclude group: '', module: 'play-services-gcm'

Advanced Integration

Excluding Metadata

When building your application, the compiler may ask you to exclude certain files in conflict. Here are some common exclusions that you can safely add to your build.gradle.

packagingOptions {
    exclude 'META-INF/LICENSE'
    exclude 'META-INF/NOTICE'
    exclude 'META-INF/LICENSE.txt'
    exclude 'META-INF/NOTICE.txt'
    exclude 'META-INF/license.txt'
    exclude 'META-INF/notice.txt'

Advanced Integration



# Upsight
-keep class** { *; }
-keep interface** { *; }

# Unity
-keep class com.unity3d.** { *; }
-keep class bitter.jnibridge.** { *; }
-keep class org.fmod.** { *; }

# Upsight mediation
-dontwarn com.upsight.mediation.**
-keep class com.upsight.mediation.** { *; }
-keep interface com.upsight.mediation.** { *; }
-keep class** { *; }
-keep interface** { *; }

# Mediation:AdColony
-keepclassmembers class * {
    @android.webkit.JavascriptInterface <methods>;
-keepclassmembers class com.adcolony.sdk.ADCNative** {*;}
-keep class com.adcolony.sdk.** { *; }
-dontwarn com.adcolony.sdk.AdColonyPubServicesPushRegIdListenerService

# Mediation:AppLovin
-keep class com.applovin.** { *; }
-dontwarn com.applovin.**

# Mediation:Mopub
-keepclassmembers class com.mopub.** { public *; }
-keep public class com.mopub.**
-keep public class android.webkit.JavascriptInterface {}
-keep class * extends com.mopub.mobileads.CustomEventInterstitial {}
-keep class * extends com.mopub.mobileads.CustomEventRewardedVideo {}
-keep class { *; }
-keep class { *; }
-keep class$Info { *; }
-dontwarn org.apache.http.**
-dontwarn com.mopub.volley.toolbox.**

# Mediation:UnityAds
-keepattributes SourceFile,LineNumberTable
-keepattributes JavascriptInterface
-keep class android.webkit.JavascriptInterface { *; }
-keep class** { *; }

# Mediation:Vungle
-keep class com.vungle.** { *; }
-keep class javax.inject.*
-dontwarn com.vungle.**

# Mediation:Ironsource
-keep class com.ironsource.adapters.** { *; }
-keep class com.moat.** { public protected private *; }
-keepclassmembers class com.ironsource.sdk.controller.IronSourceWebView$JSInterface {
    public *;
-dontwarn com.ironsource.**
-dontwarn com.moat.**

# Mediation:AdMob (optional)
-keep public class** { public *; }
-keep public class** { public *; }

# Mediation:Tapjoy (optional)
-keep class com.tapjoy.** { *; }
-keep class com.moat.** { *; }
-keepattributes JavascriptInterface
-keepattributes *Annotation*
-dontwarn com.tapjoy.**

# Mediation:Chartboost (optional)
-keep class com.chartboost.** { *; }

# HttpHeaders

# Dagger
-dontwarn dagger.**

# Gson
-keepattributes Signature
-keepattributes *Annotation*
-keep class sun.misc.Unsafe { *; }
-keep class** { *; }

# Rx
-dontwarn sun.misc.**
-keep class rx.schedulers.Schedulers {
    public static <methods>;
-keep class rx.schedulers.ImmediateScheduler {
    public <methods>;
-keep class rx.schedulers.TestScheduler {
    public <methods>;
-keep class rx.schedulers.Schedulers {
    public static ** test();
-keepclassmembers class rx.internal.util.unsafe.*ArrayQueue*Field* {
    long producerIndex;
    long consumerIndex;
-keepclassmembers class rx.internal.util.unsafe.BaseLinkedQueueProducerNodeRef {
    long producerNode;
    long consumerNode;

Analytics Module

Custom Events

Events are easier than ever to implement now. To create custom event types simply use the UpsightCustomEvent class as described below:

    .createBuilder("your_custom_message_type")  // Required event properties.
    .put(customBundle)                          // Custom property bundle.
    .put(customKey, customValue)                // Custom property override.
    .record(mUpsight);                          // Record event.

For custom events, periods can be used in the event name to create event hierarchy such as category.subcategory.my_event_name.

Tip: The permission requirements android.permission.ACCESS_NETWORK_STATE and android.permission.INTERNET are automatically merged to your application Manifest.

Tip: If you want to record an event without associating it with a particular session, such as certain interactions with an App Widget that you do not wish to count towards an app usage session, you can record the event with recordSessionless() instead.

Marketing Module


Milestones are a new way to track user movement through your app and allow you to manage exactly when and where a user sees content. Milestones are triggered when your user reaches a point in your application that you want to track or take action on.

The client tells the server that the user has reached a specific milestone in the application, by recording an UpsightMilestoneEvent as below:


Milestones have one required property—a "Scope" that uniquely describes that location in your application. Examples of Scope are "main_menu", "inventory", or "level_up".

After Milestones are implemented within the app, they need to be registered in the dashboard. To navigate there go to Settings > Applications > "App Name" > App Settings > Milestones. Then click on "Add Milestone".


“Milestone Scope” is what you called the milestone in your app. “Milestone Description” is just used to help you differentiate them.

Important "Scope" is a user defined String that must be all lowercase with no spaces.

Marketing Module


Displaying marketing content requires a "Billboard". A Billboard is like an empty frame into which the SDK can place content it receives from the server in response to a Milestone. Like Milestone events, each Billboard is associated with a Scope. Upon receiving an event, the server will send marketing content applicable to the Scope of that Milestone, which are eligible for the Billboard with matching Scope. This allows for control of when and where the content is created.

After Billboards are implemented within the application, a Campaign will need to be created in the dashboard before content will be shown.

To create a Billboard, add the following code where you feel appropriate to prepare a Billboard or to the onResume() of an Activity or Fragment:

UpsightBillboard.Handler handler = UpsightBillboardHandlers.forDefault(activity);
UpsightBillboard billboard = UpsightBillboard.create(mUpsight, scope, handler);

The Billboard created should be destroyed in the onPause() by calling billboard.destroy() to avoid unintended UI transitions. You cannot create two Billboards with the same scope unless the first one has been destroyed, or it has completed the lifecycle of displaying a unit of marketing content, in which case it is unregistered by the system and its handler.onDetach() callback has occurred.

The handler allows the client to be notified of Billboard lifecycle events when an eligible marketing content becomes available. The UpsightBillboardHandlers class provides default implementations, but the client may provide custom implementations by subclassing the defaults, or directly implementing the UpsightBillboard.Handler interface. For example, the client may wish to temporarily disable a Billboard. To accomplish this, return null when handler.onAttach() is called to skip over any marketing content that becomes available during that time.

Additionally, if you would like to check that content is ready to display before opening a billboard, you can use the isContentReady method. This method will only return true if milestone is invoked with the corresponding scope and content has been received from the server.

Tip: The permission requirement android.permission.INTERNET is automatically merged to your application Manifest.

Managed Variable Module

Upsight Managed Variables allow you to create and use values in your app that are later configurable on the Upsight Dashboard. This allows you to create new and unique experiences for your users without releasing a new version of your app to the Play Store.

To use the Upsight Managed Variables, you first need to include the Managed Variable Module as a dependency.

Then you must follow the instructions in the Managed Variables section.

Google Advertising ID Module

To use the Google Advertising ID extension, you just need to include the module as a dependency, and the extension will automatically register with the system to supply the Google Advertising ID from Google Play as needed.