Taking customer engagement to the next level with Helpshift SDK

  • If you're currently using Android SDK v7.7.0-withCampaigns or v7.7.1-withCampaigns in your app, please update the SDK to v7.7.2-withCampaigns which contains some important bug fixes. Check release notes here.
  • If you have released your app with Android SDK v7.7.0-withCampaigns and v7.7.1-withCampaigns to production, please get in touch with us via support and make sure to upgrade to v7.7.2-withCampaigns asap. Apologies for any inconvenience that this has caused.

Integration Guide

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

dependencies {
    implementation ''
    implementation ''
    implementation ''
    implementation 'com.helpshift:android-helpshift-withCampaigns-aar:7.9.2-withCampaigns'

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

Helpshift SDK comes with built-in support for 47 languages. If your app supports only a subset of these languages, please follow the steps mentioned 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:

Your unique developer API key
Domain Name
Your Helpshift domain name without any http: or slashes. E.g. happyapps if your account is
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.

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

InstallConfig installConfig = new InstallConfig.Builder().build();
try {
} catch (InstallException e) {
  Log.e(TAG, "invalid install credentials : ", e);

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

HashMap config = new HashMap();
try {
} catch (InstallException e) {
  Log.e(TAG, "invalid install credentials : ", e);

If you are using Helpshift v7.7.0-withCampaigns SDK, then call Core.init(<instance>) API only with All.getInstance() as the param.

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 v7.4.0 & above, calling any API before the install call would throw an unchecked HelpshiftInitializationException in debug mode.


From v4.6.0 & above, the Helpshift install call will throw InstallException in case the validation of the SDK keys fail.

Multi-process apps

If your app is a multi-process app, please visit the troubleshooting guide here to integrate the Helpshift SDK with your app.

Engaging with your Customers

As app developers, one of the most important aspect of making your app awesome is to constantly engage with your customers. To do this, developers need to understand their customers intricately. And this understanding will always come from data. The more data you have about your user's behaviour, the better you can engage with him.

Automatically Collected Data

The Helpshift SDK will automatically collect information about a user's device. Any data will only be collected if the app has the required permissions. User engagement data like first usage, last seen, total engagement etc will also be collected automatically by the SDK.

Device information that the SDK may collect automatically

Device model
Operating system
Language code (ISO-639-1)
Country code (ISO-3166-1 Alpha-2)
Development platform ?{"ios", "android", "phonegap", "unity"}
Native Platform ?{"ios", "android"}
Mobile Carrier
Push Opt-In
Push token
IP address
App Version
Helpshift Platform ID
Helpshift Domain
Geo Location in Lat, Long

Data Collected from Developer

There is a vast amount of data which app developers already have about an app's user. Meta-data like, what level he is currently on in a game, how much has he spent in the app, what are his preferred brands. The list can be endless. The Helpshift SDK also provides APIs for the developer to send such information to our backend. This information can be further used to create segments of users who can be targeted with an effective campaign.

Data Collection APIs

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

The com.helpshift.Campaigns class has APIs for supporting String, Integer, Long, Boolean and Date types of data.

import com.helpshift.campaigns.Campaigns;

Campaigns.addProperty("user-type", "paid");
Campaigns.addProperty("user-level", 7);
Campaigns.addProperty("last-usage", 625324123L);
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.Campaigns;

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

Verify User Properties

There is a limit of 50 user properties that can be configured. Once they’ve been configured there is no way to delete or archive old user properties. The best practice is to test campaigns with a test app. Once validated you can configure the user properties with your production apps.

Make sure to configure User Properties correctly so your team can configure segments properly with your user data. The default value of a User Property is a String value, but not all values you are passing through should be Strings.

For example:
Level = 10 should be an Integer, not a String
City = San Francisco should be a String

Other examples of correctly using User Properties:
UserID = 3493849 (Integer)
Plan Type = Enterprise (String)
Registered = false (Boolean)
Last Purchase Date = February 2, 2015 (Date)

User Management APIs

If your app allows users to log in to their accounts, you can pass along that login information to the Helpshift SDK. This will help us better identify each user. This can be further extended if your app supports multiple users too.

  • To send the login information to the Helpshift SDK, please use the com.helpshift.Core.login(String userId, String name, String email) API.
  • If you want to switch users from one to another, you can use the same API with different user credentials.
  • If you allow a user to logout of your app, you can pass on that information to us by using the com.helpshift.Core.logout() API. To logout user, do not set a dummy value as user-id.
  • Use login and logout only if you provide valid user-ids and want Helpshift to record it.

If you want to only set the name and email of the current user, you can use the com.helpshift.Core.setNameAndEmail(String name, String email) API.

Inbox APIs

Starting from version 4.4.0 the Helpshift SDK now supports rich in-app Campaign messages. These messages can contain detailed text and cover images along with customized Action buttons. All of these messages are collated in an Inbox which is provided by the Helpshift SDK out of the box. To enable the user to access his Inbox, please use the Campaigns.showInbox(Activity activity) API.


You can use the Campaigns.showInbox(Activity activity) API to show a list of In-app Campaign messages that have been received by the user.

Campaigns.showInbox(Activity activity)

Example Code :

showInbox.setOnClickListener(new OnClickListener() {
  public void onClick(View view) {


You can use the showMessage(final String mesageId, final Activity activity) API to show the Campaign message screen in response to a notification received for the Campaign.

showMessage(final String mesageId, final Activity activity)

Example Code :

showMessage.setOnClickListener(new OnClickListener() {
  public void onClick(View view) {
    Campaigns.showMessage("messageId", MyActivity.this);


If you want to display badging inside your application to indicate to the user that he has unread Campaign messages, you can use the getCountOfUnreadMessages API which will return the current count of unread campaign messages in the user's Inbox.

Inbox Data APIs

The Helpshift SDK presents a standard android like UI with the showInbox API. If your application is styled completely separately and you want to create your custom UI for the list of Campaign messages, the Helpshift SDK provides a set of APIs to power your UI based on the data that the SDK receives.


The main class which is responsible for providing the Data API is the Inbox class.

The main APIs in this class are :

  1. getInstance : Return the shared instance object of the Inbox class.
  2. deallocate : clean up any local memory which the Inbox class is using.
  3. getAllInboxMessages : Return a List of InboxMessage objects which represent the active Campaign messages for the current user. This method does not return any expired campaign.
  4. getInboxMessage : Return the InboxMessage object for the given message id. This method returns null if the message is expired for the given id.
  5. markInboxMessageAsRead : Mark the Campaign message as read by the user. This call should be used in cases where the user marks the message as read without first reading the message details Please note that this only updates the state of the object in the DB. Any UI updates that you want to make will need to be handled by the Application. This method will have no effect if called on an expired message.
  6. markInboxMessageAsSeen : Mark the Campaign message as seen by the user. This call should be used in cases where the user reads the message details. Please note that this only updates the state of the object in the DB. Any UI updates that you want to make will need to be handled by the Application. This method will have no effect if called on an expired message.
  7. deleteInboxMessage : Remove the Campaign message from the Helpshift SDK's storage.


The InboxMessage is an interface which represents the detailed Campaign message.

The APIs which are available to retrieve information from the message are:

  1. getIdentifier : Get the message identifier.
  2. getCoverImage : Get the Bitmap which was set as the cover image of the Campaign. Note, this will return null for the first time when cover image is not downloaded. After the cover image gets downloaded, it will start returning the appropriate Bitmap object. To know when the cover image gets downloaded, you need to implement the coverImageDownloaded delegate method.
  3. getIconImage : Get the Bitmap which was set as the icon image of the Campaign. To know when icon image gets downloaded, you need to implement iconImageDownloaded delegate method.
  4. getTitle : Get the title of the Campaign.
  5. getTitleColor : Get the title color of the Campaign in hex string format.
  6. getBody : Get the body of the Campaign.
  7. getBodyColor : Get the color of the body of the Campaign in hex string format.
  8. getBackgroundColor : Get the background color of the Campaign in hex string format.
  9. getReadStatus : Get the read status of the Campaign.
  10. getSeenStatus: Get the seen status of the Campaign.
  11. getCreatedAt : Get the created-at timestamp of the Campaign in seconds from 1st January, 1970.
  12. getExpiryTimeStamp : Get the expiry timestamp of the Campaign in seconds from 1st January, 1970. If administrators configure campaigns with a specific expiry time, campaign messages will not be shown after the specified expiry time. In case the Campaign has no expiry timeStamp specified, then InboxMessage.NO_EXPIRY_TIME_STAMP is returned.

    This feature is available for v4.8.0+.

  13. getCountOfActions : Get the count of action buttons that were added to the Campaign.

  14. getActionTitle : Get the title of the action button at specified index.
  15. getActionTitleColor : Get the color of the action button at specified index.
  16. getActionGoalCompletion : Get whether the action at specified index counts as goal completed for this Campaign.
  17. executeAction : Execute the action that was configured for the button at specified index.
  18. getActionType : Get the action type of button at the given index. This method returns an InboxMessage.INBOX_MESSAGE_ACTION_TYPE enum. (If an invalid index is passed, it will return enum value 'UNKNOWN'.)
  19. getActionData : Get the action data of the button at the given index. (It will be null if the action type doesn't require data.)

The relation between ActionType and ActionData :

ActionType Action data (String )
DeepLink URL
FAQs screen null
FAQ Section Section publish ID
Single FAQ FAQ publish ID
Conversation Pre-fill text
ReviewRequest URL


If you want to get delegate callbacks in response to updates to the Campaigns data in the Helpshift SDK, please set the delegate property or the inboxDelegate property of the Inbox or the Campaigns objects respectively.

For example :

// or

The methods which are part of the InboxMessageDelegate are :

  1. inboxMessageAdded(InboxMessage message) : Called when a new Campaign message is received.
  2. inboxMessageDeleted(String messageIdentifier) : Called when a Campaign message gets deleted.
  3. iconImageDownloaded(String messageIdentifier) : Called when download completes for a Campaign icon image.
  4. coverImageDownloaded(String messageIdentifier) : Called when download completes for Campaign cover image.
  5. inboxMessageMarkedAsSeen(String messageIdentifier) : Called when a campaign is seen by the user.
  6. inboxMessageMarkedAsRead(String messageIdentifier) : Called when a campaign is marked as read by the user.


If you want to intercept the push notifications received for a Campaigns inbox message, please set the InboxPushNotificationDelegate in Inbox class and override the onInboxMessagePushNotificationClicked(String messageIdentifier) method in the InboxPushNotificationDelegate interface. In response to this delegate call, you can either show your own custom UI for the campaign message screen or you can use the Campaigns.showMessage(messageIdentifier, MyActivity.this); API.

For example :


Campaigns Delegates

You have to define a class which implements Campaigns Delegates, then set this delegate instance using Campaigns.setDelegate() method.

For example :

Class Implementation:

import com.helpshift.campaigns.Campaigns;

class MyDelegate implements Campaigns.Delegate {

  public void sessionBegan() {
    // your code here

  public void sessionEnded() {
    // your code here

Class Usage:

MyDelegate delegate = new MyDelegate();


There are some guidelines which app developers need to follow to best use the Campaigns feature.

Limit On Custom User Properties

Currently there is a limit to the number of custom user properties which a developer can register for a given app.

Changes to the same property's value do not count as another property. This limitation applies to the unique keys which can be set.

The limit is 50 including the name and email properties if they are set for a given user.

Allowed values for custom user properties

The keys used for custom properties are restricted to having only alphanumeric characters. The only special characters allowed are "-" and "_", and those also need to be surrounded by alphanumeric characters. Please note that any unicode character is valid.

Examples of valid keys

  1. "level"
  2. "user-category"
  3. "is_pro"

Examples of invalid keys

  1. "$-spent"
  2. "-level-"