Campaigns

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.

Download Campaigns Enabled Helpshift Unity SDK for iOS

Download SDK v5.0.2-withCampaigns

The .zip file contains:

helpshift-plugin-unity-.unitypackage
Unity package of Helpshift SDK
HelpshiftUnityAndroidResources/
Open source project to customize the theme and string resource for Android SDK
unity-jar-resolver
Unity jar resolve package to resolve Android Helpshift package support lib dependencies

Add Helpshift to your Unity project

In case you want to use the SDK with bitcode support, follow the instructions here

  1. Import the helpshift-plugin-unity-version.unitypackage unitypackage file into your Unity game.
  2. Delesect libHelpshift-bitcode.a file while importing the unitypackage.

Using Helpshift with Bitcode support

If you want to compile your Unity iOS project with bitcode enabled, please follow the below instructions.

  1. Deselect the libHelpshift.a file when importing the Helpshift unity package.
  2. Select the libHelpshift-bitcode.a file.
  3. Once import is complete, rename the libHelpshift-bitcode.a to libHelpshift.a.

After importing the Helpshift unitypackage file, you may see errors like: Assets/Helpshift/Plugins/iOS/HsUIResourceBundle.bundle/*.png: File could not be read. These errors are shown by Unity because Apple converts traditional PNG images to a optimised CgBI format using a proprietary version of the public domain pngcrush tool making the file different from the PNG standards. This optimisation reduces the size of PNG image by almost half, making our asset folder very small in size. Unity is not able to read these images hence throws error like File could not be read.

Please ignore the import errors as they will be seen only once while importing and will not cause any run time issues.

Initializing Helpshift in your app

Helpshift's namespace

To use Helpshift's APIs, please import the Helpshift's namespace for iOS like below

using Helpshift;

Helpshift can be used to support all the apps you publish. We uniquely identify each app that is registered with Helpshift using the combination of:

API Key
This is your unique developer API Key
Domain Name
This is your helpshift instance domain name without any http: or forward slashes
App ID
This is the unique ID assigned to your app

To get the API Key, Domain Name and the App ID, navigate to Settings>SDK (for Developers) in your agent dashboard and scroll down to "Initializing Helpshift" section. show me

Select your App from the dropdown and copy the three tokens to be passed when initializing Helpshift.

Install Helpshift via CSharp

You can use the CSharp API for installing the Helpshift SDK.

using Helpshift;
.
.
.
private HelpshiftSdk help;

help = HelpshiftSdk.getInstance();
help.install("<API_KEY>", "<DOMAIN_NAME>", "<APP_ID>");

Install Helpshift via ObjC

If you intend to initialize the SDK from Xcode using Objective C, You can specify Api Key, Domain Name, App ID and other install configurations in the Objective-C code. To do this you need to override application:didFinishLaunchingWithOptions in HsUnityAppcontroller as shown below.

#import "HelpshiftCore.h"
#import "HelpshiftSupport.h"
#import "HelpshiftAll.h"
#import "Helpshift.h"
.
.
- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Set install configurations
    NSDictionary *installConfig = @{@"unityGameObject":@"background_image", @"enableInAppNotification":@"yes"};

    // Make install call
    [HelpshiftCore initializeWithProvider:[HelpshiftAll sharedInstance]];
    [HelpshiftCore installForApiKey:@"<your_api_key>" domainName:@"<your_domain_name>.helpshift.com" appID:@"<your_app_id>" withOptions:installConfig];

    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

In order to receive callbacks from Helpshift, you must pass a valid game object for unityGameObject key in the install configuration.

Required UIApplicationDelegate functions

For its internal functioning, Helpshift needs to override below mentioned functions of UIApplicationDelegate protocol. The class HsUnityAppController overrides these functions as required. These methods are called by external iOS services and expect the application to call completionHandler(). By default, UnityAppController class does not implement these functions. If you require any of these functions of other features of your app, you must override these functions, comment out or remove default completionHandler() call and provide your own implementation as per your requirements.

- (void) application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)())completionHandler {
    if (![HelpshiftCore handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler]) {
        // Handle events for background url session. Once you have implemented this function in UnityAppController, uncomment
        // the code below and comment the call completionHandler();

        //[super application:application handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
        completionHandler();
    }
}

- (void) application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)userInfo completionHandler:(void (^)())completionHandler {

    if (![HelpshiftCore handleInteractiveRemoteNotification:userInfo forAction:identifier completionHandler:completionHandler]) {

        // Handle action with identifier. Once you have implemented this function in UnityAppController, uncomment
        // the code below and comment the call completionHandler();

        //[super application:application handleActionWithIdentifier:identifier forRemoteNotification:userInfo completionHandler:completionHandler];
        completionHandler();
    }
}

- (void) application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forLocalNotification:(UILocalNotification *)notification completionHandler:(void (^)())completionHandler {
    if(![HelpshiftCore handleInteractiveLocalNotification:notification forAction:identifier completionHandler:completionHandler]) {
        // Handle action with identifier. Once you have implemented this function in UnityAppController, uncomment
        // the code below and comment the call completionHandler();

        //[super application:application handleActionWithIdentifier:identifier forLocalNotification:notification completionHandler:completionHandler];
        completionHandler();
    }
}

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

Description
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
Timezone
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 HelpshiftCampaigns.AddProperty APIs.

The HelpshiftCampaigns class supports these data types:

  • String
  • Integer
  • Boolean
  • Date
  • Long [Available from plugin v2.9.0 and above]

For Example:

using Helpshift.Campaigns;
.
.
.

HelpshiftCampaigns campaigns = HelpshiftCampaigns.getInstance();
campaigns.AddProperty("level", 7);
campaigns.AddProperty("user-type", "paid");
campaigns.AddProperty("is-pro", true);
campaigns.AddProperty("last-ride", DateTime.Now);
campaigns.AddProperty("coins", 9223372036854775807);

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

HelpshiftCampaigns.getInstance().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 HelpshiftSdk.getInstance().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 HelpshiftSdk.getInstance().logout() API.

If you want to only set the name and email of the current user, you can use the HelpshiftSdk.getInstance().setNameAndEmail() API.

Inbox APIs

Starting from version 2.3.1 the 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 HelpshiftCampaigns.ShowInbox(Dictionary config) API.

showInbox

Use the HelpshiftCampaigns.ShowInbox(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> ();
HelpshiftCampaigns.getInstance().ShowInbox(config);

ShowMessage

You can use the ShowMessage(String mesageIdentifier, Dictionary config) API to show the Campaign message screen in response to a notification received for the Campaign.

Definition
ShowMessage(String mesageIdentifier)

Example Code :

Dictionary<string,object> config = new Dictionary<string,object> ();
HelpshiftCampaigns.getInstance().ShowMessage("messageId", config);

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 IHelpshiftCampaignsDelegate. 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:

HelpshiftCampaigns.RequestUnreadMessagesCount ()

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

public void didReceiveUnreadMessagesCount(int count)
{
    Debug.Log ("Campaigns : didReceiveUnreadMessagesCount : " + count);
}

Delegates and Notification Count

  • Applicable to plugin v2.9.0 & above.

Inbox Data API's

The Helpshift SDK presents a standard iOS 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.

HelpshiftInbox

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

The main APIs in this class are :

  1. GetInstance : Return the shared instance object of the HelpshiftInbox class.
  2. GetAllInboxMessages : Return a List of HelpshiftInboxMessage objects which represent the active Campaign messages for the current user. This method does not return any expired campaign.
  3. GetInboxMessage : Returns the HelpshiftInboxMessage object for the given message id. This method returns null if the message is expired for the given 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. This method will have no effect if called on an expired message.
  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. This method will have no effect if called on an expired message.
  6. DeleteInboxMessage : Remove the Campaign message from the Helpshift SDK's storage.

HelpshiftInboxMessage

The HelpshiftInboxMessage is an interface which represents a detailed Campaign message.

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

  1. GetIdentifier : Get the message identifier.
  2. GetCoverImageFilePath : Get the file path of the image which was set as the cover image of the Campaign.
  3. GetIconImageFilePath : Get the file path of the image which was set as the icon image of the Campaign.
  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 milliseconds 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.
  13. HasExpiryTimestamp : In case the Campaign has no expiry timestamp specified, then this method will return false, true otherwise.
  14. GetCountOfActions : 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. GetActionGoalCompletion : 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. For iOS, the second parameter of this method should be null.
  19. GetActionType : Get the action type of button at the given index. This method returns an HelpshiftInboxMessageActionType enum. (If an invalid index is passed, it will return enum value 'UNKNOWN'.)
  20. 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

IHelpshiftInboxDelegate

If you want to get callbacks in response to the updates of Campaigns data in the Helpshift SDK, please implement the IHelpshiftInboxDelegate interface and set it in Helpshift SDK via calling HelpshiftInbox.SetInboxMessageDelegate() or HelpshiftCampaigns.SetInboxMessageDelegate() api.

Callbacks to this interface are not guaranteed to be on the UI thread of the application.

For example :

HelpshiftInbox.getInstance().SetInboxMessageDelegate(this);
// or
HelpshiftCampaigns.getInstance().SetInboxMessageDelegate(this);

The methods which are part of the IHelpshiftInboxDelegate are :

  1. InboxMessageAdded(HelpshiftInboxMessage 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.

IHelpshiftInboxPushNotificationDelegate

If you want to intercept the push notifications received for a Campaigns inbox message, please set the implementation of IHelpshiftInboxPushNotificationDelegate interface in the HelpshiftInbox class via calling HelpshiftInbox.SetInboxPushNotificationDelegate() api.

In response to this callback, you can either show your own custom UI for the campaign message screen or you can use the HelpshiftCampaigns.showMessage(messageIdentifier); API.

Callbacks to this interface are not guaranteed to be on the UI thread of the application.

For example :

HelpshiftInbox.getInstance().SetInboxPushNotificationDelegate(this);

IHelpshiftCampaignsDelegate

Delegate interface for reporting Campaigns events. Set the implementation of IHelpshiftCampaignsDelegate interface in the HelpshiftCampaigns class via calling HelpshiftCampaigns.SetCampaignsDelegate() api.

Callbacks to this interface are not guaranteed to be on the UI thread of the application.

For example :

HelpshiftCampaigns.getInstance().SetCampaignsDelegate(this);

Unread message count

didReceiveUnreadMessagesCount(int count)

Invoked in response to HelpshiftSdk.RequestUnreadMessagesCount() API call.

Session delegates

Campaigns Session Began

sessionBegan

Implement this delegate callback to track when a Helpshift campaigns session starts in your app. This delegate will get fired every time a Helpshift campaigns session starts.

Campaigns Session End

sessionEnded

Implement this delegate callback to track when a Helpshift campaigns session ends in your app. This delegate will get fired every time a Helpshift campaigns session ends.

    public class CampaignsDelegate : IHelpshiftCampaignsDelegate
    {
        public void didReceiveUnreadMessagesCount(int count) {
            Debug.Log ("Campaigns : didReceiveUnreadMessagesCount : " + count);
        }

        public void sessionBegan() {
            Debug.Log("** Helpshift Campaigns Session Has Begun **");
        }

        public void sessionEnded() {
            Debug.Log("** Helpshift Campaigns Session Has Ended **");
        }
    }

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.

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

For iOS 9 and above, developers need to whitelist the URL Schemes which their App will query.

You must whitelist any URL Schemes that your App wants to query in your Info.plist file under the LSApplicationQueriesSchemes key:

This will Also impact the apps the apps which are not built with the iOS 9 SDK.