Skip to main content

Proactive Engagement

Proactive Engagement lets you reach out to your players by sending Push/In-App Messages on their mobile devices and engage in various ways including starting conversations.

Note
  • Proactive Engagement is available from SDK X 10.5.0 onwards.
  • All the public APIs in the SDK should be called after initializing the SDK via Helpshift.install() API
  • Before starting with Proactive Engagement, please ensure that you have integrated push notifications with Helpshift SDK. Please refer Notifications section for integration guide.
  • Please note that the SDK does not ask for posting notifications permission for client application. For Proactive Engagement, you need to ask for the POST_NOTIFICATION permission yourself.

Configuring Proactive Engagement Campaign​

To publish an Engagement Campaign follow these steps:

  • Open the Helpshift Dashboard and navigate to Settings > Workflows > Proactive Engagement
  • Create an Engagement campaign for the app you want with either Push or In-App message
Helpshift admin dashboard settings for Proactive Engagement feature
  • Select the desired action from available options, fill up the message content and add context as per your needs.
    • Intents/CIFs/tags/initial message etc configured here will be used when the end user starts a conversation by clicking on the message.
Proactive Engagement campaign compose settings on Helpshift admin dashboard
  • Configure the audience filter that you want to target. You can filter the audience based on:
Proactive Engagement campaign audience filter on Helpshift admin dashboard
  • Schedule the engagement campaign. You will get a chance to review the full configuration before publishing the campaign.
Proactive Engagement campaign scheduling on Helpshift admin dashboard

Push Message​

Proactive Engagement push message on Android
  • Push-type messages will be shown in the Notification tray of the device.
  • Use this type of message when you want to re-engage the user who has not been active or grab attention of users with some interesting information.
  • With the various actions available on click of the message or the buttons in the message, you can redirect the user to any part of your application via deeplinks (need to be setup by the client application) or start a conversation via “Start Chat“ option or redirect them to an FAQ for quick help.
  • Push messages will show up even if the app is not running in background.
  • Rich text is supported in the content of the message. Make sure you provide compatible/supported HTML content used for setting up the message on Dashboard.
    • Due to system limitations, rich text in messages is not supported from Android 16 unless Android fixes it.

In-App Message​

Banner

Card

Modal

  • In-App messages are used to grab attention of the user who is already using your application, is on the application UI and you want to alert or engage them.
  • If the user is not currently using the app, we show the in-app message when the application is opened next time. This way an in-app message is not lost even if user is not on the application screen.
  • We currently support Banner type messages with click actions similar to Push messages.
  • Note:
    • If the SDK receives multiple in-app messages when the app was in background then the SDK will show only the latest received in-app message and discard all the older ones.
    • By default, In-App messages expire in 2 days from the time of delivery to the device. If in-app received in background expires, then SDK will not show the expired in-app message.

Behaviour in different configurations​

ConfigurationBehaviour
App not registered for Push NotificationsNo Proactive Push or In-App notifications will be received.
Registered for push but Notification Permissions not grantedNo Push notifications. In-App notifications will show when the app is next opened.
Registered and Notification Permissions GrantedPush will be displayed in device notification tray and In-App notifications will be seen the next time the user opens the app.
In-App Expiry Time2 days from time of delivery.

Delegate Push Message to Helpshift SDK​

  • Integrating handling of Proactive Engagement message requires no extra effort if push message were already integrated for Helpshift SDK messages.
  • Refer Push Notifications integration page.

Setting defaults for message properties​

  • If you need to set some defaults to be used in proactive messages then you can use this API. We recommend to call this API right after Helpshift.install() call.
  • Following configurations are available via this api
    • notificationIconId : Android resource id, integer value, for small icon to be used for proactive message. If not configured then app icon will be used by default.
    • largeNotificationIconId : Android resource id, integer value, for large message image. This will be used when an image is not configured in the message on Dashboard.
    • soundId : Android resource id, integer value, for the sound to be used for proactive message. If not provided then system default sound will be used. Note that this sound will be associated with the default message channel that SDK creates for Proactive Engagement messages. Refer below section.

Custom message channels for Proactive Engagement messages​

  • If you want to set your own message channels (i.e. these channels are created by the client application beforehand) for Proactive Engagement messages then you can pass on the values in this API.
  • If the values are not set then the SDK creates default message channel by itself.
    • For proactive Engagement messages that lead to Helpcenter or Conversations it will create a channel by name: “Proactive Support“
    • For proactive Engagement messages that lead to user engagement it will create a channel by name: “Proactive Engage“
  • You can provide your own channel Ids to be used by the SDK via this API:
    • proactiveSupportChannelId: Channel id for Proactive support cases.
    • proactiveEngageChannelId: Channel id for Proactive Engage cases.
API:Helpshift.setProactivePushNotificationDefaults()
Values:Map<String, Object>
Min SDKv10.5.0
Should be called afterinstall()

Example:

public class MainApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // Install call
    Helpshift.install(this, "<PLATFORM_ID>", "<DOMAIN>", configurations);

    Map<String, Object> defaults = new HashMap<>();
    defaults.put("notificationIconId", R.drawable.icon);
    defaults.put("largeNotificationIconId", R.drawable.large_icon);
    defaults.put("soundId", R.drawable.sound);
    defaults.put("proactiveSupportChannelId", "Customer Channel name");
    defaults.put("proactiveEngageChannelId", "Customer Channel name");

    Helpshift.setProactivePushNotificationDefaults(defaults);
  }
}

Pausing In-App Messages​

  • This API will pause/unpause the showing of in-app messages to the end user when application is in foreground.
  • You can use this API to pause in-app messages when you know that the user should not be disturbed. For example, the user is on app startup screen, the app is still loading, user is in game play or on a payment screen etc. In such cases you can pause the in-app messages from Helpshift SDK and once the user is done you can unpause it via the same API.
  • Note that in-app messages received when the messages were paused are not lost, they are shown to the user as soon as the messages are unpaused again.
  • This API needs to be called in every app session since SDK will not persist its value across sessions. The need to pause/unpause in-app messages is real time and depends on the current application state best known to the client application itself, hence the SDK does not persist the value across app sessions.
  • By default the SDK will always show the in-app messages unless explicitly paused by the client app by using this API.
  • shouldPauseInAppNotification: Set to false by default.
    • false: Starts showing the in-app messages, if available.
    • true: Pauses the in-app messages. In-app messages received during the time, i.e when this value was true, are shown when this value is later set to false.
API:Helpshift.shouldPauseInAppNotification()
Values:boolean
Min SDKv10.5.0
Should be called afterinstall()
public class MainActivity extends AppCompatActivity{
  @Override
  public void onCreate() {
    super.onCreate();
    //... Assuming Helpshift.install() is already called in Application.onCreate()

    // based on state of your app, decide to pause/unpause proactive engagement notifications.
    Helpshift.shouldPauseInAppNotification(true/false);

    //...
  }

Passing fallback configuration​

  • You may want to add configuration specific to the current user in your app when interacting with proactive messages.
  • This configuration is used when no configuration is provided from the Dashboard when configuring the message. This configuration data is exactly same as we would expect in other APIs like showConversation() or showFAQs().
  • We will also use this configuration for the next issue filed in the same session. For example, if the user starts a conversation via proactive engagement message and the conversation gets resolved in the same session and the user starts another conversation then this configuration will be used for the new conversation.
  • Note: You need to call this API after Helpshift.install() API and before Helpshift.handlePush()
  • Implement public interface com.helpshift.proactive.HelpshiftProactiveAPIConfigCollector and call Helpshift.setHelpshiftProactiveConfigCollector("<instance of HelpshiftProactiveAPIConfigCollector>") method to initialize the config collector.
  • You will have to implement the method getAPIConfig() where you can add any user specific config in the same format as you add in other public APIs like showConversation() or showFAQs().
  • HelpshiftProactiveAPIConfigCollector.getAPIConfig() is invoked by the SDK before handling the message click action and evaluating the configuration to be used for handling the message.
  • For example, following code shows how to implement HelpshiftProactiveAPIConfigCollector interface and how to add user specific configurations using getAPIConfig() method -
public class MainActivity extends AppCompatActivity implements HelpshiftProactiveAPIConfigCollector {
  @Override
  public void onCreate() {
    super.onCreate();
    //... Assuming Helpshift.install() is already called in Application.onCreate()

    // initialise proactiveConfig collector
    Helpshift.setHelpshiftProactiveConfigCollector(this);

    //...
  }

  //...

  @Override
  public Map<String, Object> getAPIConfig() {

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

    // set tags for tracking
    localConfig.put("tags", new String[]{"currentUserTag", "currentUserLevel"});

    // 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);

    localConfig.put("cifs", cifMap);
    // ..etc
    return localConfig;
  }
}
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.