Getting Started

Getting started with integrating Helpshift in your Android app.

Gradle based projects

Add the following dependencies to your build.gradle file inside the dependencies section.

    dependencies {
        implementation 'com.android.support:appcompat-v7:28.0.0'
        implementation 'com.helpshift:helpshift-sdkx:10.3.0'
    }

Helpshift SDK comes with built-in support for 47 languages. An API to change SDK language is provided. More details here.

Helpshift is now ready to help you have conversations with your users!

Initialize Helpshift in your App

Helpshift uniquely identifies each registered App with a combination of 2 tokens:

Domain Name	Your Helpshift domain. E.g. happyapps.helpshift.com
Platform ID	Your App's unique platform id (App's App Id on dashboard is your platform Id)

You can find these by navigating to `Settings`>`SDK (for Developers)` in your agent dashboard. Select your App and _check Android as a platform_ from the dropdowns and copy the 2 tokens to be passed when initializing Helpshift.

Initialize SDK by calling com.helpshift.Helpshift.install() method.

    public class MainApplication extends Application {
    @Override
      public void onCreate() {
        super.onCreate();
        // Add install configs in the config map
        Map<String, Object> config = new HashMap<>();
        //...
        // Install call
        try {
            Helpshift.install(this,
                      "<App Id from the Helpshift Dashboard>",
                      "<Domain name from the Helpshift Dashboard>",
                      config);
        } catch (UnsupportedOSVersionException e) {
            // Android OS versions prior to Lollipop (< SDK 21) are not supported.
        }
      }
    }

Important

Placing the install call

You should not place the install call anywhere other than Application.onCreate Placing it elsewhere might cause unexpected runtime problems.

HelpshiftInitializationException

Calling any API before the install call would throw an unchecked HelpshiftInitializationException in debug mode.

UnsupportedOSVersionException

Calling install() below android SDK version 21 will throw this checked exception. All the APIs will be non operable.

Minimum supported Android version

The Helpshift SDK for Android requires minimum API level to be 16. However, all the Helpshift's public apis will be non-operable below android SDK version 21.

Integrating Feedback Screen

You can call Helpshift.showConversation(MyActivity.this, configurationMap) to lead your user to your feedback section. It is advised to add configurationMap.put("initialUserMessage", "Give Feedback"); before this call to add Initial User Message.

Example:

    // config map
    Map<String, Object> config = new HashMap<>();

    // set tags for tracking
    config.put("tags", new String[]{"foo", "bar"});

    // set custom issue fields
    Map<String, Object> cifMap = new HashMap<>();
    Map<String, String> isPro = new HashMap<>();
    isPro.put("type", "boolean");
    isPro.put("value", "true");
    cifMap.put("is_pro", isPro);

    config.put("cifs", cifMap);
    config.put("initialUserMessage", "Give Feedback");

    //..etc

    // pass the config map in the api
    Helpshift.showConversation(MainActivity.this, config);

Note

The "customIssueFields" key has been deprecated. We strongly recommend transitioning to using the "cifs" key as the preferred method for passing custom issue fields.

Helpshift.showConversation(MyActivity.this, configMap); where MyActivity.this is the Activity you're calling Helpshift from and configMap is the configuration map that you want to pass to configure the SDK.

Integrating FAQs

Example: Helpshift.showFAQs(MyActivity.this, configMap); where MyActivity.this is the Activity you're calling Helpshift from. It is advised to add configMap.put("initialUserMessage", "Give Feedback"); before this call to add Initial User Message to your FAQs.

You can use the api call Helpshift.showFAQs(Activity a, Map<String, Object> configMap) to provide a way for the user to invoke the purpose built help/FAQs section in your app. This is the easiest approach to enable help in your app as it bundles all the capabilities of the Helpshift SDK in a simple and intuitive interface. You can wire this api call to a "Help" or "FAQs" action in your app. This Activity combines the FAQ, Search and Give Feedback functionality together in a single interface. In this view a user has to search for a specific question in the FAQ.

Adding Custom Metadata to Feedback

You can attach additional metadata to every new feedback started by the app user. This metadata can include properties like username, email, game scores, current game levels, and any other data needed to provide relevant context for each new feedback. You can attach custom metadata by passing it to the configMap object at the time of calling any of the SDK APIs (showConversation, showFAQs) like Helpshift.showConversation(this, configMap).

Use code:

HashMap<String, String> customMetadata = new HashMap<String, String();
customMetadata.put("usertype","paid");
customMetadata.put("level","7");
customMetadata.put("score","12345");

HashMap<String, Object> config = new HashMap<>();
config.put("customMetadata", customMetadata);

Helpshift.showConversation(MainActivity.this, config);

Note

Metadata should only be sent as String key-value pairs.

Set Custom Issue Fields

Note

On Custom Issue Fields keys & compatibility

• Custom Issue Fields must be created in the Helpshift Dashboard (Settings → Custom Issue Fields), otherwise they will be ignored. Read more here

If you want to set Custom Issue Fields at the time of Issue creation, follow the steps.

1. Initialise a top level custom issue fields' Map
2. Define your custom issue field Map
3. Add the "type" and "value" for that custom issue field
4. Add the custom issue field map to top level map (with key as your configured key and value as custom issue field map)
5. Pass the map to configMap with key "cifs" of the Helpshift.showConversation(this, configMap)

    Map<String, Object> joiningDate = new HashMap<>();
    joiningDate.put("type", "date");
    joiningDate.put("value", 1505927361535L);

    Map<String, String> stockLevel = new HashMap<>();
    stockLevel.put("type", "number");
    stockLevel.put("value", "1505");

    Map<String, String> employeeName= new HashMap<>();
    employeeName.put("type", "singleline");
    employeeName.put("value", "Bugs helpshift");

    Map<String, String> isPro = new HashMap<>();
    isPro.put("type", "boolean");
    isPro.put("value", "true");

    Map<String, Object> cifMap = new HashMap<>();
    cifMap.put("joining_date", joiningDate);
    cifMap.put("stock_level", stockLevel);
    cifMap.put("employee_name", employeeName);
    cifMap.put("is_pro", isPro);


    Map<String, Object> config = new HashMap<>();
    // other configs...
    //..
    config.put("cifs", cifMap);

    Helpshift.showConversation(MainActivity.this, config);

Note

The "customIssueFields" key has been deprecated. We strongly recommend transitioning to using the "cifs" key as the preferred method for passing custom issue fields.

The following are the valid values for the type key of a Custom Issue Field.

• "singleline"
• "multiline"
• "number"
• "checkbox"
• "dropdown"
• "date"

Compatibility table for type and values:

Type	Value	Comments
singleline	string	Character limit of 255
multiline	string	Character limit of 100,000
number	string
dropdown	string	Drop-down options should exist for the given Custom Issue Field
date	number	Epoch time. For example - Date.now()
checkbox	boolean