Campaigns

User story

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.

Case 1

Imagine you want to have a Drip marketing campaign which will send messages to your users, specific number of days after the app is installed. In order for you to be able to do this, you need to know when every user first installs your app. And then you need a mechanism to send messages to all such users. With the new Helpshift SDK, you will be able to find and segment all such users and then target them with a continuously running campaign. All the data needed for this will be collected by the SDK automatically.

Case 2

Bringing users back in to the app is most critical for any app which wants to be successful. In order for a developer to do this, he needs to have data about when was the last time every user engaged with the app. Once that information is available, developer can start a continuous campaign which can send effective messages to the user. All the data required to achieve this will be collected by the Helpshift SDK automatically without the developer having to do any work.

Case 3

App ratings are the ultimate measure of an app's popularity and success. The more ratings an app will have, the more visible it becomes which will ultimately mean more customers. But asking your users to rate your app is a critical decision. You want to maximize the chances of the user actually taking the time to rate your app. In order to do this, you must target the users who are your most frequent users. People who use the app most frequently. To do this, you need to collect analytics data about app sessions from all your users. The new Helpshift SDK will do this automatically for you. Moreover, it will collate this information for you from all devices that a particular user will use.

Case 4

The most effective way to make customers happy is to give them what they want. And to do this, you need a system to get their feedback. The Helpshift SDK can help you target a specific group of people based on engagement metrics or even custom data which the app can collect about the user. Feedback coming from the users will be in the form of support tickets which can be acted upon via the Helpshift admin dashboard.

Case 5

So let's say you built an awesome new feature and rolled out the update. But how do you make sure your users know about it ? And furthermore, how do you get them to go and upgrade the apps ? You can easily do this if you have the right data, and the mechanism for creating a segment of users to target. You can even go ahead and add an FAQ which explains the feature in detail. This can be combined with a call to action for going to the App Store and updating the app which can ensure maximum visibility for all your features.

Getting started

Developers who want to use the Helpshift SDK to take customer engagement to the next level, need to start from the most important step, collecting data. To do this, you need to integrate the latest Helpshift SDK into your app.

Data collected automatically

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 which the SDK may collect automatically.

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.

Campaigns API

To start collecting rich meta-data about your user, use the HelpshiftApi.HelpshiftCampaigns.AddProperty APIs.

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

    HelpshiftApi.HelpshiftCampaigns.AddProperty("level", 7);
    HelpshiftApi.HelpshiftCampaigns.AddProperty("last-usage", 625324123L);
    HelpshiftApi.HelpshiftCampaigns.AddProperty("user-type", "paid");
    HelpshiftApi.HelpshiftCampaigns.AddProperty("is-pro", true);
    HelpshiftApi.HelpshiftCampaigns.AddProperty("last-ride", DateTime.Now);

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

HelpshiftApi.HelpshiftCampaigns.AddProperties(Dictionary<string, object> properties);

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 HelpshiftApi.HelpshiftCore.Login 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 HelpshiftApi.HelpshiftCore.Logout() API.

If you want to only set the name and email of the current user, you can use the HelpshiftApi.HelpshiftCore.SetNameAndEmail() API.

Inbox APIs

Helpshift SDK 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 HelpshiftApi.HelpshiftCampaigns.ShowInbox(Activity, Dictionary<>) API.

ShowInbox

Use the HelpshiftApi.HelpshiftCampaigns.ShowInbox(Activity activity, Dictionary config) API to show a list of In-app Campaign messages that have been received by the user. (Presently "config" argument is not used, so it can be empty/null)

Example Code :

Dictionary<string,object> config = new Dictionary<string,object> ();
HelpshiftApi.HelpshiftCampaigns.ShowInbox(activity, config);

ShowMessage

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

Example Code :

HelpshiftApi.HelpshiftCampaigns.ShowMessage(activity, messageIdentifier);

RequestUnreadMessagesCount

If you want to show your user notifications for unread campaign messages, you can use unread message counts provided by Helpshift SDK and display it as a badge. You can get notification counts asynchronously by implementing the ICampaignsDelegate. The badges can be displayed anywhere in your app's interface to tell the user that they have unread campaign messages from you.

For example:

// Register the delegate
HelpshiftApi.HelpshiftCampaigns.SetCampaignsDelegate(new CustomCampaignsDelegate());

// Request the unread messages count
HelpshiftApi.HelpshiftCampaigns.RequestUnreadMessagesCount ()

You will receive the count in DidReceiveUnreadMessagesCount(int count) delegate.

public class CustomCampaignsDelegate : Java.Lang.Object, ICampaignsDelegate
{
    public void DidReceiveUnreadMessagesCount(int count)
    {
       // Code
    }
}

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.

HelpshiftApi.HelpshiftInbox

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

The main APIs in this class are :

1. CleanUp : Clean up any local memory which the Inbox class is using.
2. GetAllInboxMessages : Returns a list of InboxMessage objects which represent the Campaign messages for the current user.
3. GetInboxMessageForId : Returns the InboxMessage object for the given message id.
4. 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.
5. 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.
6. DeleteInboxMessage : Remove the Campaign message from the Helpshift SDK's storage.

InboxMessage

The HelpshiftApi.InboxMessage represents the detailed Campaign message.

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

1. Identifier : Get the message identifier.
2. CoverImageFilePath : 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. If the cover image got downloaded, it will start returning the appropriate file path. To know when the cover image gets downloaded, you need to implement the CoverImageDownloaded delegate method as mentioned here.
3. IconImageFilePath : Get the Bitmap which was set as the icon image of the Campaign.
4. Title : Get the title of the Campaign.
5. TitleColor : Get the title color of the Campaign in hex string format.
6. Body : Get the body of the Campaign.
7. BodyColor : Get the color of the body of the Campaign in hex string format.
8. BackgroundColor : Get the background color of the Campaign in hex string format.
9. ReadStatus : Get the read status of the Campaign.
10. SeenStatus: Get the seen status of the Campaign.
11. CreatedAt : Get the created-at timestamp of the Campaign in milliseconds from 1st January, 1970.
12. HasExpiryTimeStamp : Returns whether the Inbox message has an expiry timestamp configured by the administrator.
13. ExpiryTimeStamp : 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.
14. CountOfActions : Get the count of action buttons that were added to the Campaign.
15. GetActionTitle : Get the title of the action button at specified index.
16. GetActionTitleColor : Get the color of the action button at specified index.
17. IsActionGoalCompletion : Get whether the action at specified index counts as goal completed for this Campaign.
18. ExecuteAction : Execute the action that was configured for the button at specified index.
19. GetActionType : Get the action type of button at the given index. This method returns an InboxMessageActionType enum. (If an invalid index is passed, it will return 'Unknown')
20. GetActionData : Get the action data of the button at the given index. (It will be null if the action type doesn't need data)

The relation between ActionType and ActionData :

IInboxMessageDelegate

If you want to get delegate callbacks in response to updates to the Campaigns data in the Helpshift SDK, please set the callback interface in HelpshiftApi.HelpshiftInbox or the HelpshiftApi.HelpshiftCampaigns objects respectively.

For example :

HelpshiftApi.HelpshiftInbox.SetInboxMessageDelegate(<Implementation of IInboxMessageDelegate>);
// or
HelpshiftApi.HelpshiftCampaigns.SetInboxMessageDelegate(<Implementation of IInboxMessageDelegate>);

The methods which are part of the IInboxMessageDelegate 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 imageFilePath) : 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.

IInboxNotificationDelegate

If you want to intercept the push notifications received for a Campaigns inbox message, please set the IInboxNotificationDelegate in HelpshiftApi.HelpshiftInbox class and override the InboxMessagePushNotificationClicked(string messageIdentifier) method in the IInboxNotificationDelegate 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 HelpshiftApi.HelpshiftCampaigns.ShowMessage(activity, messageIdentifier); API.

If this delegate is set then Helpshift will not show the message on tapping the notification. The developer is expected to show the UI as required via listening to the callbacks.

For example :

HelpshiftApi.HelpshiftInbox.SetInboxNotificationDelegate(<Implementation of IInboxNotificationDelegate>);

Campaigns Delegates

You have to define a class which implements Helpshift Campaigns Delegates ICampaignsDelegate and then pass this to Helpshift using HelpshiftCampaigns.SetCampaignsDelegate(campaignsDelegate); method. For example:

For example :

Class Implementation:

using HelpshiftApi;

public class CustomCampaignsDelegate : ICampaignsDelegate
{

        public void DidReceiveUnreadMessagesCount(int count)
        {
            // your code here
        }

        public void SessionBegan()
        {
           // your code here
        }

        public void SessionEnded()
        {
            // your code here
        }
}

Class Usage:

ICampaignsDelegate campaignsDelegate = new CustomCampaignsDelegate();
HelpshiftCampaigns.SetCampaignsDelegate(campaignsDelegate);

The methods of the interface ICampaignsDelegate are:

1. DidReceiveUnreadMessagesCount(int count) : Callback method for HelpshiftCampaigns.RequestUnreadMessagesCount() API.
2. SessionBegan(): The delegate will fire each time the Helpshift Campaigns session starts.
3. SessionEnded(): The delegate will fire each time the Helpshift Campaigns session ends.

Impact On Your App

Our experience with building a successful SDK has taught us valuable lessons. Keep it as simple as possible for the developer, and minimize resource usage on the user's device. Collecting large amounts of data and sending it back to servers can be a resource heavy operation. To make sure we reduce impact, the Helpshift SDK uses an effective and easily configurable data syncing strategy to sync data with our servers. This strategy also takes into account the current network type and battery levels of the user's device.

Data Syncing

The basis for the strategy is that we only sync data when the app goes into background. This makes sure that we do not interfere with critical network resources when the user is using the app. App developers do not need to do anything special in order to enable this behaviour.

Batching

Another important aspect to collecting large amounts of atomically small data is batching. We have also made sure that we batch our data optimally and only sync data when the batch of data we have is significant.

Engagement Metrics

For engagement metrics, studies have shown that an average user of an app will have roughly 8 to 10 sessions per day. So we make sure that we sync once every 24 hours or if we have 5 or more sessions recorded with us.

Custom User Properties

For custom properties provided by the developer, the SDK will sync once every 24 hours or if 2 or more properties have changed their values.

Device Metrics

For device related metrics, the SDK will sync data with a daily frequency of 4. This translates to sync interval of 6 hours. So device properties will sync once every 6 hours, only if there is new data to be synced.

Guidelines

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

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.

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-"