Upsight logo Back to top

Getting Started

Javadocs


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 "https://nexus.upsight.com/nexus/content/repositories/upsight-android-release/"
        }
        ...
    }
}

To include all the standard Upsight modules, simply add:

compile 'com.upsight.android:all:4.8.0'

If you would like to use Mediated Ads, also include:

compile 'com.upsight.android:mediation:4.8.0'

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>

    <!-- Application token and public key from Upsight Dashboard -->
    <meta-data
        android:name="com.upsight.app_token"
        android:value="UPSIGHT_APPLICATION_TOKEN" />
    <meta-data
        android:name="com.upsight.public_key"
        android:value="UPSIGHT_PUBLIC_KEY" />

    <!-- e.g. android:authorities="com.yourCompany.yourApplication.upsight" -->
    <provider
        android:name="com.upsight.android.internal.persistence.ContentProvider"
        android:authorities="APPLICATION_PACKAGE_NAME.upsight"
        android:enabled="true"
        android:exported="false" />
</application>

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;

    @Override
    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 com.upsight.android:all, you can selectively add each dependency as appropriate to your application:

compile 'com.upsight.android:analytics:4.8.0'             // To use the Analytics module.
compile 'com.upsight.android:marketing:4.8.0'             // To use the Marketing module.
compile 'com.upsight.android:managed-variables:4.8.0'     // To use the Managed Variables module.
compile 'com.upsight.android:google-advertising-id:4.8.0' // To use the Google Advertising ID module.
compile 'com.upsight.android:google-push-services:4.8.0'  // To use the Google Push Services module.
compile 'com.upsight.android:marketplace:4.8.0'           // To use the Marketplace module.
compile 'com.upsight.android:mediation:4.8.0'             // To use the Mediation 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:

compile ('com.upsight.android:google-advertising-id:4.8.0') {
    exclude group: 'com.google.android.gms', module: 'play-services-ads'
}
compile ('com.upsight.android:google-push-services:4.8.0') {
    exclude group: 'com.google.android.gms', 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

ProGuard


-dontobfuscate

# Upsight
-keep class com.upsight.android.** { *; }
-keep interface com.upsight.android.** { *; }
-dontwarn com.upsight.android.UpsightContext
-dontwarn com.upsight.android.marketing.internal.vast.VastContentModel

# 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 com.google.android.gms.ads.identifier.** { *; }
-keep interface com.google.android.gms.ads.identifier.** { *; }

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

# 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 com.google.android.gms.common.GooglePlayServicesUtil { *; }
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient { *; }
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info { *; }
-dontwarn com.google.android.gms.**
-dontwarn org.apache.http.**
-dontwarn com.mopub.volley.toolbox.**

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

# 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 com.google.android.gms.ads.** { public *; }
-keep public class com.google.ads.** { 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
-dontwarn com.google.common.net.HttpHeaders

# Dagger
-dontwarn dagger.**

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

# 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:

UpsightCustomEvent
    .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


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:

UpsightMilestoneEvent.createBuilder(scope).record(mUpsight);

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".

Milestones

“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

Billboards


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.