Android

Installation

To install Pulse Insights in your application, follow those steps:

1. Add the maven repositories target and the google repositories target in the build.gradle script of the project level as the following example shows. Make sure you have google() in the top of repositories section in both of buildscript and allprojects

buildscript {
    repositories {
        google()
        ...
    }
}
allprojects {
    repositories {
        google()
        ...
        maven {
            url  "https://pi-sdk.s3.us-east-1.amazonaws.com/android"
        }
        ...

    }
}

2. Add the dependencies description in the build.gradle script of the app level as the following example shows.

dependencies {
    ...
    implementation 'com.pulseinsights:android-sdk:2.3.0'
}

You only need to modify this implementation description with the available version name when you want to update the SDK in the future.

3. Sync the gradle script

4. If your app is targeting API level 28 (Android 9.0) or above, please make sure the following <uses-library> element description has been added inside the <application> element of AndroidManifest.xml. Check the developer documentation for more detail.

  <uses-library
      android:name="org.apache.http.legacy"
      android:required="false" />

Usage

1. Initialization

When your application starts, you should initialize the library using the snippet below:

PulseInsights pi = new PulseInsights([context], YOUR_ACCOUNT_ID);

Replace YOUR_ACCOUNT_ID with your own PulseInsights ID, for example: PI-12345678.

You should subclass Application and provide a helper method that returns your application's PulseInsights object:

public class PulseInsightsApplication extends Application {

  private PulseInsights pi;

  synchronized public getPulseInsights() {

      if(pi == null)
          pi = new PulseInsights(this, YOUR_ACCOUNT_ID);

      return pi;
  }
}

You also need to provide the context of the Activity object to display the survey view or the invite widget.

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        pi.setContext(Context context)
        ...
    }

After this initial step, you can fetch the PulseInsights object as below:

new PulseInsights([context]);

2. View tracking

PulseInsights allows targeting surveys to a given screen name. In order for the SDK to know the current screen name, you can use the following method to notify it of the current screen name change:

pi.setViewName(String viewName);

For example, you can override the onCreate function or the onActivityResult function on the Activity class:

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        pi.setViewName("cus_MainActivity");
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == MainActivity_REQUEST) {
            String result = data.getExtras().getString("result");
            if (result.equalsIgnoreCase("BACK_ACTIVITY")) {
                pi.setViewName("cus_MainActivity");
            }
        }
    }

3. Survey polling

The PulseInsights SDK will automatically regularly fetch surveys that would match various targeting conditions based on a frequency that you can override as shown below:

pi.setScanFrequency(int frequencyInSecond);

If you want to manually fetch new surveys, you can use this method:

pi.serve();

4. Render a specific survey

It is also possible to manually trigger a survey by its id:

pi.present(String surveyID);

5. Inline surveys

Inline surveys are rendered within the content of the application, instead of overlaying the application content.

In order to integrate inline surveys, you can programmatically create the InlineSurveyView object by assigning an identifier and inserting it into a view:

InLineSurveyView inlineView = new InLineSurveyView(Context context, String trackId);

You still can integrate inline surveys by adding the inline survey on the XML layout with the survey view class com.pulseinsights.pisurveylibrary.util.InlineSurveyView

<com.pulseinsights.pisurveylibrary.util.InlineSurveyView
            android:id="@+id/inline_survey"
            android:layout_width="match_parent"
            />

In this case, you can assign the identifier on the inline view by using the method setIdentifier

InlineSurveyView inlineSurvey;
inlineSurvey = (InlineSurveyView) itemView.findViewById(R.id.inline_survey);
inlineSurvey.setIdentifier(String trackId);

6. Survey rendering

You can pause and resume survey rendering with the following method:

pi.switchSurveyScan(boolean enable);

And check the current configuration with the following method:

• true: survey rendering feature is enabled

• false: survey rendering feature is paused

boolean renderingConfig = pi.isSurveyRenderingActive();

It is also possible to pause the survey rendering feature from the initialization of the Pulse Insights library:

ExtraConfig piConfig = new ExtraConfig();
piConfig.automaticStart = false;
PulseInsights pi = new PulseInsights(Context context, String accountId, ExtraConfig piConfig);

You can check this article for learn more about the ExtraConfig class.

7. Client Key

Client key can be set using this method:

pi.setClientKey(String clientKey);

The configured client key can be fetched with this method:

String getKey = pi.getClientKey();

8. Preview mode

Preview mode can be enabled or disabled by:

Shaking the device more than 10-times in 3-seconds

Preview mode can be programmatically enabled/disabled by this method:

pi.setPreviewMode(boolean enable)

It is also possible to set the preview mode from the initialization of the Pulse Insights library:

ExtraConfig piConfig = new ExtraConfig();
piConfig.previewMode = true;
PulseInsights pi = new PulseInsights(Context context, String accountId, ExtraConfig piConfig);

You can check this article for learn more about the ExtraConfig class.

In order to check the status of preview mode, use this method:

boolean isPreviewModeOn = pi.isPreviewModeOn()

9. Callbacks

If you want to know if a survey has been answered by the current device, this method can be used:

boolean answered = pi.checkSurveyAnswered(String surveyId);

It is also possible to configure a callback to be executed when a survey has been answered:

pi.setAnswerListener(new SurveyAnsweredListener() {
                    @Override
                    public void onAnswered(String answerId) {

                    }
                });

10. Context data

You can save context data along with the survey results, or for a refined survey targeting, using the customData config attribute, for example:

ExtraConfig piConfig = new ExtraConfig();
piConfig.customData = new HashMap<String, String>();
piConfig.customData.put("gender", "male");
piConfig.customData.put("age", "32");
piConfig.customData.put("locale", "en-US");
PulseInsights pi = new PulseInsights(Context context, String accountId, ExtraConfig piConfig);

You can check this article for learn more about the ExtraConfig class.

11. Device data

If you want to set device data, which will be saved along the survey results, the method setDeviceData can be used as follows:

pi.setDeviceData(Map<String, String> map);

setDeviceData can be called at any time, it will trigger a separate network request to save the data.

12. Advanced

The default host is "survey.pulseinsights.com". If you want to target the staging environment, or any other environment, it's possible to override the default host:

pi.setHost(String surveyID);

The debug mode can be turned on and off:

pi.setDebugMode(boolean enable);

PulseInsights creates a unique UDID to track a given device. If you wish to reset this UDID, you can call the following method:

pi.resetUdid();

If you want to manually config the context, you can call the following method:

pi.setContext(Context context)

And get the context object that has been configured

Context context = pi.getContext()

13. Others

1. ExtraConfig

The ExtraConfig is the class to which you can apply the additional configuration from the initialization of the Pulse Insights library:

ExtraConfig piConfig = new ExtraConfig();
piConfig.automaticStart = false;
PulseInsights pi = new PulseInsights(Context context, String accountId, ExtraConfig piConfig);

You can apply the additional config with the following sub variables:

Name	function	Default	Usage
automaticStart	Survey rendering	true	true - survey rendering will automatically started from the initialization false - survey rendering will not started from the initialization
previewMode	Preview mode	false	true - turn preview mode on false - turn preview mode off
customData	Context data	new HashMap<>()	Save data along with survey results

Themes

You can configure approximately 50 properties such as font color and size using SDK Themes in the Console:

Styling is not driven by CSS, but uses native components & formatting instead.

To create a mobile app compatible theme in the Pulse Insights Console:

1. Click the Settings dropdown menu from the top navigation bar

2. Select "Themes"

3. Click the "New Theme" button

4. Give a name to your theme

5. In the "Type" dropdown menu, select "Native"

6. Input your Native JSON theme into the code box

7. "Update"

Uninstall

Remove 1.0.9 or later

1. Remove whatever you added when you go through the install flow

2. Sync or rebuild your project

Remove 1.0.8 or earlier

To remove the library from your project, please follow the steps below:

1. In the IDE, select [File]->[Project Structure]

2. Select Modules from the left menu and find the library you named when you installed. Select remove or -, then click ok to confirm.

3. Find and remove the following implementation statement from the dependencies section from the app level build.gradle script file.

dependencies {
    ...
    implementation project(path: ':pisurveylibrary')
}

4. Open the project folder, find and delete the sub-folder with the library display name.