Install Gainsight PX SDK for Android

Integrate Gainsight PX Editor 

Gainsight PX Mobile Editor helps you manage PX engagements and Product Mapper from your mobile application. 

The In-app Editor allows you to:

• Preview engagements in the mobile app
• View the Product Tree
• Create, edit and delete Module/Features 
• Add Tap Rules for Module/Features

To use the in-app editor, copy the Scheme to integrate your mobile application with the your platforms that Gainsight supports.

You can activate the editor using deep linking and forwarding the link to the SDK. While forwarding the information, you as a developer have the ability to implement your own logic and permissions before launching the editor.

Prerequisite: Deep linking must be enabled to access the Gainsight PX Editor. For more information on how to create deep links, refer to the Android documentation article.

To integrate Gainsight PX with the Android platform:

1. Add the following to your app AndroidManifest.xml file, in the main activity part:

<intent-filter>       
        <data android:scheme="{SCHEME}" />
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <category android:name="android.intent.category.DEFAULT" />
</intent-filter>               

Note: Setting host attribute is not required.

2.  After initializing the GainsightPX instance, call the following on the code for the same activity:

  if ((null != intent) && (null != intent.getScheme())) {
            GainsightPX.with().enterEditingMode(intent);
  }

Note: You can use the same code on onNewIntent method as well:

if ((null != intent) && (null != intent.getScheme())) {
           GainsightPX.with().enterEditingMode(intent);
 }          

Initialize

IMPORTANT: The following settings are the default configurations that are suitable for clients that are on the US data centers. For clients that are from EU or US2 data centers need to modify the default configurations mentioned in the Gainsight PX Configurations section as per the requirement. 

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

4. Configure the Builder with the required custom configurations.
5. Call the Builder.build function to create a new instance of Gainsight PX, by using the following code.

GainsightPX instance = builder.build();

6. Setup Gainsight PX as a singleton instance, by using the following code.

GainsightPX.setSingletonInstance(instance);

IMPORTANT: 

• You can call the above function if hardreset is not applied  to it and you can reset the function.
• You can call the GainsightPX.with(), to start collecting data from your application, after setting the singleton instance. 

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.

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

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

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

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

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

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

General Methods

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

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().setGlobalContext(globalContextData);

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

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

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

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

EngagementCallBack

Gainsight PX provides the Engagement Callback feature for mobile engagements that you create for mobile applications. This feature helps in receiving a callback for all button actions and URL clicks that the end-user performs on an engagement. Once you receive the callback, you can decide your next action like helping the user to navigate to a new screen, or perform an API call and so on.

Prerequisite

Ensure that you have installed/configured the Gainsight PX Mobile SDK v1.5.1 or above.

To use the Engagement Callback feature for Android devices, you need to implement the EngagementCallback interface. 

Example:

public class GlobalEngagementCallback implements GainsightPX.EngagementCallback {

private static GainsightPX.EngagementCallback instance;
private final Context context;

private GlobalEngagementCallback(Context context) {
  this.context = context;
}

public static GainsightPX.EngagementCallback instance(Context context) {
  if (null == instance) {
    synchronized (GlobalEngagementCallback.class) {
      if (null == instance) {
        instance = new GlobalEngagementCallback(context.getApplicationContext());
      }
    }
  }
  return instance;
}

@Override
public boolean onCallback(EngagementMetaData engagementMetaData) {
  // Here you can do your functionality based on the callback.
  return true;
}
}

While you initialize the SDK with the below function:

GainsightPX.Builder builder = new GainsightPX.Builder(Context context, String YOUR_PRODUCT_ID);

You can add the EngagementCallback functionality as follows:

builder.engagementCallback(GlobalEngagementCallback.instance(this))

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().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().identify(@NonNull String userId, GlobalExceptionHandler.instance(context));