Getting Started

Or, follow these simple steps to add Helpshift in-app support to your Android app right away -

If you want to upgrade your project from Helpshift SDK version v3.12.0 or below please refer to the upgrade guide.

Integration Guide

Version Requirements

Helpshift SDK Version minSDKVersion targetSDKVersion compileSDKVersion buildToolsVersion
>= 4.7.0 14 24 24 24
>= 4.4.0 14 23 23 23
>= 4.0.0 and < 4.4.0 16 23 23 23

For example, update your AndroidManifest.xml as follows:

<uses-sdk android:minSdkVersion="14" android:targetSdkVersion="24"
          android:compileSDKVersion="24" android:buildToolsVersion="24" />

Gradle based projects

Internationalized SDK

Helpshift SDK which comes with built-in support for 47 languages. Add the following dependencies to your build.gradle file inside the depencencies section.

dependencies {
    compile 'com.android.support:design:24.2.0'
    compile 'com.android.support:recyclerview-v7:24.2.0'
    compile 'com.android.support:cardview-v7:24.2.0'
    compile 'com.helpshift:android-helpshift-aar:4.8.1'
}

design, cardview and recyclerview library are required by the Helpshift SDK, make sure they've also been added .

English only SDK

If you want to support English only, add the following dependencies to your build.gradle file inside the depencencies section.

dependencies {
    compile 'com.android.support:design:24.2.0'
    compile 'com.android.support:recyclerview-v7:24.2.0'
    compile 'com.android.support:cardview-v7:24.2.0'
    compile 'com.helpshift:android-helpshift-en-aar:4.8.1'
}

design, cardview and recyclerview library are required by the Helpshift SDK, make sure they've also been added .

Helpshift is now ready to help you have conversations with your users! Move on to Initializing Helpshift in your App.


IntelliJ/Eclipse based projects

If your Android project is based on IntelliJ or Eclipse, download the latest version of the Android SDK.

The zip file contains the Helpshift SDK in the Android Library Project format.


Maven based projects

If your Android project is based on Maven, follow the steps here.

Start using Helpshift

Helpshift is now integrated in your app and ready to provide customer support and collect meaningful data about your users.

Initialize Helpshift in your App

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

API Key
Your unique developer API key
Domain Name
Your Helpshift domain name without any http: or slashes. E.g. happyapps if your account is happyapps.helpshift.com
App ID
Your App's unique ID
You can find these by navigating to Settings>SDK (for Developers) in your agent dashboard. Select your App and the correct platform from the dropdowns and copy the 3 tokens to be passed when initializing Helpshift. show me

Initialize Helpshift by calling the com.helpshift.Core's install method by doing the following.

  1. Initialize the Core class with the Helpshift service that you want to use.
  2. Call the Core's install method.

com.helpshift.Core is the class which encapsulates all the functions which are common to all Helpshift services. Currently we have HelpshiftCampaigns and HelpshiftSupport as the 2 available services.

import com.helpshift.Core;
import com.helpshift.All;
import com.helpshift.InstallConfig;
import com.helpshift.exceptions.InstallException;
...
...

InstallConfig installConfig = new InstallConfig.Builder().build();
...
Core.init(All.getInstance());
try {
  Core.install(this,
               "YOUR_API_KEY",
               "YOUR_DOMAIN_NAME",
               "YOUR_APP_ID",
               installConfig);
} catch (InstallException e) {
  Log.e(TAG, "invalid install credentials : ", e);
}

import com.helpshift.Core;
import com.helpshift.All;
...
...

HashMap config = new HashMap();
...
Core.init(All.getInstance());
try {
  Core.install(this,
               "YOUR_API_KEY",
               "YOUR_DOMAIN_NAME",
               "YOUR_APP_ID",
               config);
} catch (InstallException e) {
  Log.e(TAG, "invalid install credentials : ", e);
}

Placing the install call

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

From version 4.6.0 and above the Helpshift install call will throw InstallException in case the validation of the SDK keys fail.

Support APIs

If you want to add support sections inside your app with Helpshift, you can use the com.helpshift.support.Support APIs. All the APIs which were available in the com.helpshift.Helpshift class are now available in the new Support class.

For example,

com.helpshift.support.Support.showConversation(Activity activity);

Campaigns APIs

To start collecting rich meta-data about your user, use the Campaigns.addProperty() APIs.

The com.helpshift.Campaigns class has APIs for supporting strings, integers, booleans and date types of data.

import com.helpshift.Campaigns;
...
...

Campaigns.addProperty("user-type", "paid");
Campaigns.addProperty("user-level", 7);
Campaigns.addProperty("is-pro", false);
Campaigns.addProperty("last-ride", new Date());

If you want to add multiple properties together, you can use the Campaigns.addProperties() API which takes a Map which represents the user meta-data in terms property-value pairs.

import com.helpshift.Campaigns;
...
...

HashMap properties = new HashMap();
properties.put("user-type", "paid");
properties.put("user-level", 7);
...
Campaigns.addProperties(properties);

Minimum supported SDK version

From SDK version 4.4.0 onwards, the Helpshift Android SDK requires minimum API level to be 14. For versions 14 and 15 you will not receive the rich push notifications which are only supported after android api level 16.

Troubleshooting

If you are having issues with Helpshift integration, head over to the Troubleshooting section for further information.

Next up

If you've successfully tested out an in-app conversation, it's time to dive into these advanced topics -

Helpshift APIs

Discover ways to do customer support via Helpshift.

Design

Theming and Skinning your SDK to look like your App.

Going International

Localizing & Internationalizing your in-app Support.

Notifications

Configure Push and In-app notifications.

Tracking

Track events and user actions. Attach custom metadata to every conversation.

Reviews & Feedback

Asking for reviews and feedback.

Additional Configuration

  • If you are using Proguard, you will need to add the following to your project's proguard-project.txt file.

    -keep class android.support.v4.** { *; }
    

    Helpshift Android SDK v2.8.2 and above is not pre-obfuscated with Proguard. To shrink & obfuscate the Helpshift SDK, we recommend you use this Proguard configuration in your project.

    Proguard is recommended for shrinking, optimizing, and obfuscating your code by removing unused code and renaming classes, fields, and methods with semantically obscured names. The result is a smaller sized APK file that is more difficult to reverse engineer. For more information refer Proguard Documentation

  • In your build.xml file, insert the following between the <target name="-post-compile"> tags. This will check the Helpshift xml files for the requisite resources and warn you if any of those resources are missing. If the "-post-compile" target is missing, wrap the below code snippet with <target name="-post-compile">...</target> tags.

    <path id="helpshift-classpath">
      <fileset dir="<path/to/Helpshift-SDK/libs>">
        <include name="Helpshift.jar"/>
      </fileset>
    </path>
    <java classname="com.helpshift.HSPostCompileCheck" failonerror="true">
      <classpath refid="helpshift-classpath"/>
      <arg value="<YOUR_APPLICATION_NAMESPACE>"/>
    </java>