Skip to main content
Gainsight Inc.

Install Gainsight PX SDK for Android

ATTENTION: Documentation Updates are in Process
We are in the process of updating the screenshots, GIFs, and content to match the latest UX based on the Horizon Experience’s new look and feel. To learn more about the Horizon Experience in Gainsight PX, click here.

This article explains how developers can use Gainsight PX’s Android SDK to set it up in their application. 

Overview

The Gainsight PX Android SDK is a powerful tool that can measure your application’s statistics and provide you with powerful insights about your app. This article explains the various facets of including Gainsight PX Android SDK in your Android app. 

Gainsight PX provides you with an Android archive (.aar extension) file. You can use this file to set up a project in any mobile application development platform. (This article uses the Android Studio application.)   

This addresses five key steps:

Add Android Archive File to Project

This section explains how you can use the Gainsight PX .aar file in your project. 

  1. Download and extract the Gainsight PX .aar file.
  2. Launch the Android Studio application.
  3. Navigate to File > New > New Module.

1..png

  1. Select the Import .JAR/ .AAR Package and click Next.

2..png

  1. Click the folder icon, navigate to the location of your .aar file, and select it.
  2. Click Finish.

3..png

  1. Add the newly created module as a dependency module of other modules:

    1. Right-click your Gainsight PX module and select Open Module Settings.

4..png

  1. Click Dependencies in the left pane.
  2. Click + and select Module dependency.

5..png

  1. Select the checkbox for the required modules.
  2. Click OK.

6..png

Configuration Setup

This section explains how to get started with Gainsight PX mobile app development. You can customize the default settings as required. This section explains both cases.

Customize Settings

You can modify the default settings, to match your specific requirements.

To use the custom setting:

  1. Create a subclass of the Android Application class.
  2. Declare the subclass in the Android.Manifest file. 
  3. Override the onCreate method to start an instance of GainsightPX.Builder, by using the following code.
GainsightPX.Builder builder = new GainsightPX.Builder(Context context, String YOUR_PRODUCT_ID);
  1. Configure the Builder with the required custom configurations.
  2. Call the Builder.build function to create a new instance of Gainsight PX, by using the following code.
GainsightPX instance = builder.build();
  1. Setup Gainsight PX as a singleton instance, by using the following code.

GainsightPX.setSingletonInstance(instance)

IMPORTANT

  • You can call the above function only once and you cannot reset it.
  • You must call the GainsightPX.with(Context), to start collecting data from your application. 

Error Handling 

All exceptions occurred when creating events are passed into error callback GlobalExceptionHandler.


public class GlobalExceptionHandler implements GainsightPX.ExceptionHandler {  private static GainsightPX.ExceptionHandler instance;
  private Context context;  private GlobalExceptionHandler(Context context) {
    this.context = context;
  }  public static GainsightPX.ExceptionHandler instance(Context context) {
    if (null == instance) {
      synchronized (GlobalExceptionHandler.class) {
        if (null == instance) {
          instance = new GlobalExceptionHandler(context.getApplicationContext());
        }
      }
    }
    return instance;
  }  @Override
  public void onExceptionOccurred(String methodName, ValueMap params, String exceptionMessage) {
    String text = "Exception occurred in: " + methodName + ", With the message: " + exceptionMessage;
    GainsightPX.with(context).logger(Constants.GAINSIGHT_TAG).debug(text);
  }
}

The properties of onExceptionOccurred  are as follows:

  • The first parameter (methodName) informs about the invoked function name.
  • The second parameter (params) gives the event properties that were sent to create an event.
  • The error parameter (exceptionMessage) informs about the exception that occurred.

IMPORTANT:

You can add Exception Handler to any of the following methods: 

  • Builder
  • Screen
  • Identify
  • Custom

Example

GainsightPX.with(Context).identify(@NonNull String userId, GlobalExceptionHandler.instance(context));

Gainsight PX Configurations

This section describes methods, whose configurations can be modified by you during the initialization stage.

Method Call Default Description Override by Server?
flushQueueSize (int size) 20 The number of events that are considered to form a batch to be sent to the server. Once this limit is reached, PX sends the events to the server even if it's still not the time for that (by the timer) Yes
flushInterval (long value, TimeUnit unit) 30 sec The time interval during which the client checks if there are any new events to send to the server Yes
collectDeviceId (boolean collect) true Whether or not to collect the device id from the device No
tag (String tag) {PRODUCT_ID} Custom string to be used as part of the log string No
logLevel (LogLevel logLevel) NONE Which log level should be logged to CatLog. By default, none will be logged No
crypto (Crypto crypto) None Enables to add encryption for the data that is stored locally No
trackApplicationLifecycleEvents (boolean shouldTrack) true Should the client auto track app related events (APP_OPENED, APP_INSTALLED and APP_UPDATED) No (Server can drop the event based on remote configuration)
shouldTrackTapEvents false

Should the client auto-track tap events

Note: Enabling this helps you track only the single tap gestures.

Yes
recordScreenViews (boolean shouldRecord) true Whether or not the client should auto track No (Server can drop the event based on remote configuration)
proxy (String proxyHost) null There's an option to send the network requests via proxy (mainly for security checks) Yes
connectionTimeout (int value, TimeUnit unit) 15 sec Network connection timeout for getting any response from the server Yes
readTimeout (int value, TimeUnit unit) 20 sec Network connection timeout for fully completing the network request Yes
trackApplicationCrash      

Create Events

This section explains how to create events that can track data from your mobile application. Events are actions associated with your app and allow you to track various actions performed by users on your app. Currently, the Gainsight PX SDK supports four types of events.

App Events 

App events track general operations performed on your application. App events do not require any configurations. The Gainsight SDK auto collects App events from your application. However, if you disable the App events collection, these events are not collected. The app events collected are as follows:

Event Name Description
APP_OPENED Tracks every instance of customers launching your application.
APP_INSTALLED Tracks every instance of customers installing your application.
APP_UPDATED Tracks every instance of customers updating your application.

Gainsight PX is also looking to launch two additional app events in the future; APP_BACKGROUNDED and APP_CRASHED. The former tracks every instance of your application running in the background and the latter tracks every instance of an app crash. However, these events are not auto-enabled, and have to be configured.

Screen Events

Screen events track various screens of your application, traversed by a user. By default, Gainsight PX tracks the screens of your application visited by users (if the user moves from the first screen to the second screen and then returns to the first screen, it is tracked automatically). However, in some situations, you need to explicitly register screen views. To help you in such situations, Gainsight PX has the following functions with PUBLIC access specifier:

GainsightPX.with(Context).screen(@NonNull String screenName);

You can also create a screen event with additional properties (for example, parameters created for starting the page), as a map, by using the following code. 

GainsightPX.with(Context).screen(@NonNull String screenName, @Nullable final Map properties);

You can also create a screen event with fully loaded details like screen class, information from the intent that created the activity and so on. To accomplish this, use the following code.

GainsightPX.with(Context).screen(@NonNull final ScreenEventData eventData);

Screen name is a mandatory argument to use any of the above functions.

Identify Events

These events are used to identify a user uniquely. Gainsight PX SDK provides you with three functions to identify users.

GainsightPX.with(Context).identify(@NonNull String userId);
GainsightPX.with(Context).identify(@NonNull User user);
GainsightPX.with(Context).identify(@NonNull User user, final @Nullable Account account);

User ID is a mandatory argument to use any of the above functions. You can also use the User and Account objects to uniquely identify users. While creating either the User or the Account object, you must provide an ID. You can add more attributes to user information. There are setter methods for common attributes. However, you can add custom attributes using the following code:

user.putCustomAttributes(Map customAttributes);
account.putCustomAttributes(Map customAttributes);

Custom Events

Custom Events are used to track specific events on your app. Currently, every button click is also tracked as a custom event. However, in future releases, button clicks will be tracked automatically. The functions of custom events are:

GainsightPX.with(Context).custom(@NonNull String event);
GainsightPX.with(Context).custom(final @NonNull String event, final @Nullable Map properties);

Event Name is a mandatory argument. You can also add event properties to track further details of the event that occurred.

Global Context 

A global context can be set on the variables. You can set a global context with key-value pairs and send it with the payload. Global context can be set with Date, String, Double, and Boolean data types. Global Context data is stored at the memory level and not disk-level. The key-value pairs are sent with the Payloads. If an application is terminated, all the key-value pairs are erased. 

The following code snippet can be used to set the global context data fields: 

globalContextData = new GlobalContextData();
globalContextData.putString(key, stringValue);
globalContextData.putNumber(key, longValue);
globalContextData.putNumber(key, intValue);
globalContextData.putNumber(key, doubleValue);
globalContextData.putBoolean(key, booleanValue);
globalContextData.putDate(key, dateObject);
globalContextData.putDate(key, <#[String object with ISO8601 format]#>);
globalContextData.putDate(key, <#[long for unix time in millisec]#>);

The following code snippet can be used to set the global context data fields:

GainsightPX.with(Context).setGlobalContext(globalContextData);

The following code snippet can be used to check if the key is available:

if ((GainsightPX.with(Context).getGlobalContext() != null) && (GainsightPX.with(Context).getGlobalContext().hasKey("key"))) {}

The following code snippet can be used to remove the key from the global context:

GainsightPX.with(Context).getGlobalContext().removeKey("key"{, "key2"...});

General Methods

This section describes the general methods (functions) of Gainsight PX SDK. There are three general methods:

Method Name Method Description
Flush GainsightPX.with(Context).flush(); This method sends all events on the queue to the server, by ignoring the scheduled auto flush. Generally, you need not use this method but there could be situations in which you may need to flush out events. 
Reset GainsightPX.with(Context).reset(); This method resets all user events. This method is generally used only when a user logs out of your application so that all future events can be grouped as part of the next login.
Enable/Disable GainsightPX.with(Context).setEnable(boolean enable);

boolean enabled = GainsightPX.with(Context).enabled();
These methods help you to enable or disable event tracking on your app. When you use the disable method, no event is sent to the server. You can use the disable method on data sensitive areas of your app.
  • Was this article helpful?