Skip to main content

Proactive Engagement

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

Note
  • This feature 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 you have integrated push notifications with Helpshift SDK. Please refer Notifications Android and Notifications iOS page 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 notifications​

To publish a notification follow these steps:

  • Open the Helpshift Dashboard and navigate to Settings > Workflows > Proactive Engagement
  • Create a notification for the app you want with either Push or In-App notification
Helpshift admin dashboard settings for Proactive Engagement feature
  • Select the desired action from available options, fill up the notification 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 notification.
Proactive Engagement notification compose settings on Helpshift admin dashboard
  • Configure the audience filter that you want to target. You can filter the audience based on:
Proactive Engagement notification audience filter on Helpshift admin dashboard
  • Schedule the notification. You will get a chance to review the full configuration before publishing the notification.
Proactive Engagement notification scheduling on Helpshift admin dashboard

Push notifications​

Proactive Engagement push notification on Android
  • Push type notifications will be shown in the Notification tray of the device.
  • Use this type of notification 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 notification or the buttons in the notification, 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 notifications will show up even if the app is not running in background.
  • Rich text is supported in the content of the notification. Make sure you provide compatible/supported HTML content used for setting up the notification on Dashboard.
    • Due to system limitations, rich text in notifications is not supported from Android 16 unless Android fixes it.

In-App Notifications​

Proactive Engagement in-app notification on Android
  • InApp notifications are used to grab attention of the user who is already using your application, is on the application UI and you want to alert/engage them.
  • If the user is not currently using the app, we show the in-app notification when the application is opened next time. This way an in-app notification is not lost even if user is not on the application screen.
  • We currently support Banner type notifications with click actions similar to Push notifications.
  • Note:
    • If the SDK receives multiple in-app notifications when the app was in background then the SDK will show only the latest received in-app notification and discard all the older ones.
    • By default, In-App notifications 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 notification.

Pausing In-App Notifications​

  • This API will pause/unpause the showing of in-app notifications to the end user when the application is in the foreground.
  • You can use this API to pause in-app notifications when you know that the user should not be disturbed. For example:
    • The user is on the app startup screen or the app is still loading.
    • The user is in active gameplay.
    • The user is on a payment or checkout screen.
  • In-app notifications received while they are paused are not lost; they are shown to the user as soon as the notifications are unpaused.
  • This API needs to be called in every app session because the SDK does not persist its value across sessions. The state of your app (e.g., whether the user is in gameplay) is best known to your application in real-time.
  • By default, the SDK will always show in-app notifications (pauseDisplayOfInAppNotification is effectively false) unless explicitly paused.
  • Values:
    • true: Pauses in-app notifications.
    • false: Resumes showing in-app notifications (default behavior).
KeyDetails
APIpauseDisplayOfInAppNotification(shouldPause: bool)
Valuestrue (Pauses), false (Resumes)
Min SDKv10.5.0
NoteAfter calling HelpshiftCocos2dx::install()

Example:

#import "HelpshiftCocos2dx.h"

// To temporarily pause in-app notifications (e.g., during gameplay)
HelpshiftCocos2dx::pauseDisplayOfInAppNotification(true);

// To resume showing the in-app notifications
HelpshiftCocos2dx::pauseDisplayOfInAppNotification(false);

Setting defaults for notification properties (Android)​

If you need to set some defaults to be used in proactive notifications on Android, you can use the setAndroidProactivePushNotificationDefaults API. We recommend calling this API right after the install() call.

The following configurations are available via this API:

  • notificationIconId: Notification icon file name without extension, for the small icon to be used for proactive notifications. If not configured, the app icon will be used by default.
  • largeNotificationIconId: Large notification icon file name without extension. This will be used when an image is not configured in the notification on the Helpshift Dashboard.
  • soundId: Sound resource name without extension, for the sound to be used for proactive notifications. If not provided, the system default sound will be used. Note that this sound will be associated with the default notification channel that the SDK creates for Proactive Engagement notifications.
  • proactiveSupportChannelId: Custom channel ID for Proactive support cases (notifications leading to Helpcenter or Conversations).
  • proactiveEngageChannelId: Custom channel ID for Proactive Engage cases (notifications leading to user engagement).
KeyDetails
APIsetAndroidProactivePushNotificationDefaults(config: object)
PlatformAndroid only
Min SDKv10.5.0
NoteAfter calling HelpshiftCocos2dx::install()

Example:

import com.helpshift.HelpshiftCocosBridge;

public class MyActivity extends Cocos2dxActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Install call
        HelpshiftCocosBridge.install(...);

        HashMap<String, Object> proactiveDefaults = new HashMap<>();
        proactiveDefaults.put("notificationIconId", "<icon-image-file-name>");
        proactiveDefaults.put("largeNotificationIconId", "<large-icon-image-file-name>");
        proactiveDefaults.put("soundId", "<sound-file-name>");
        proactiveDefaults.put("proactiveSupportChannelId", "Customer Channel name");
        proactiveDefaults.put("proactiveEngageChannelId", "Customer Channel name");

        HelpshiftCocosBridge.setProactivePushNotificationDefaults(proactiveDefaults);
    }
}

Custom notification channels for Proactive Engagement notifications​

If you want to use your own notification channels (created by your application beforehand) for Proactive Engagement notifications, you can provide the channel IDs via the API above.

If the values are not set, the SDK creates default notification channels automatically:

  • Proactive Support: For notifications leading to Helpcenter or Conversations. Default name: "Proactive Support".
  • Proactive Engage: For notifications leading to user engagement. Default name: "Proactive Engage".

For more details on these configuration options and custom notification channels, please refer to the Android Notification Defaults section.

Passing configuration specific to the current user​

You may want to add configuration specific to the current user in your app when they click on the notification.

Setting local API config enables the Helpshift SDK to merge configuration from both, the config embedded in the outbound support link (as mentioned in previous steps) and the local config provided at runtime. This local API config is exactly same as we would expect in other APIs like showConversation() or showFAQs().

We will use this configuration for current issue as well as next issue filed in same session.

Note

You need to call this API after install API and before HelpshiftCocosBridge.handlePushNotification()

You will have to create 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().

We will merge this config and the config embedded in the outbound support link. We will append data of config from outbound support link to local config like Tags, CIFs, etc. In case of conflicts, outbound support config will get the precedence.

For example, following code shows how to set proactive config collector using setHelpshiftProactiveConfigCollector delegate and how to add user specific configurations using getAPIConfig() method -

cocos2d::ValueMap createValueMap(const std::string& type, Value value) {
    cocos2d::ValueMap valueMap;
    valueMap["type"] = cocos2d::Value(type);
    valueMap["value"] = cocos2d::Value(std::move(value));
    return valueMap;
}

cocos2d::ValueMap getCifs() {
    cocos2d::ValueMap cifMap;

    cifMap["joining_date"] = createValueMap("date", Value("1684747527945"));
    cifMap["stock_level"] = createValueMap("number", Value("1500"));
    cifMap["employee_name"] = createValueMap("singleline", Value("Captain Marvel"));

    return cifMap;
}

cocos2d::ValueMap getAPIConfig() {
    cocos2d::ValueMap configMap;

    //set tags for tracking
    ValueVector tags;
    tags.push_back(Value("vip"));
    tags.push_back(Value("payment"));
    tags.push_back(Value("renewal"));
    configMap["tags"] = tags;

    //set custom issue fields
    configMap["cifs"] = getCifs();

    return configMap;
}

// init method of your UI
bool HelloWorld::init()
{
    //////////////////////////////
    // 1. super init first
    if ( !Scene::init() )
    {
        return false;
    }
    ...
    ...
    HelpshiftCocos2dx::setHelpshiftProactiveConfigCollector(getAPIConfig);
}