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 you have integrated push messaging with Helpshift SDK. Please refer Notifications page for integration guide.

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

• 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.

• Configure the audience filter that you want to target. You can filter the audience based on:
  • Issue properties
  • User properties using User Hub integration

• Schedule the engagement campaign. You will get a chance to review the full configuration before publishing the campaign.

Push Message

• Push-type messages will be shown in the iOS Notification Center. 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 content.
• With the various actions available on click of 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 the background.

Note

• Buttons in Push message is not supported for iOS
• Rich text is not supported in the content of the message

iOS: Notification Service Extension Requirement

To support Proactive Engagement push messages with rich content on iOS (for example, image-based messages), your app must include a Notification Service Extension (NSE).

If your app already has a Notification Service Extension, you can reuse it. Otherwise, follow the setup instructions on the Notifications iOS page.

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 with him in real time.
• If the user is not on the application UI then the message is shown in the notification tray of the device to engage the user.
• When the user clicks on the message we open the app and then present the actual configured in-app message. This increases the probability of user engagement and helps us achieve our goal better.
• We currently support Banner type messages with click actions similar to Push messages.
• If the SDK receives multiple in-app messages when the app was in background then the system will display all of them. On clicking the message, we will open the app and the SDK will show in-app message corresponding to the clicked message. Other messages remain as is in the notification center.
• By default, In-App messages expire in 2 days from the time of delivery to the device. If user clicks on a message that has already expired then on click no action will be taken.

Behaviour in different configurations

Configuration	Behaviour
App not registered for Push Notifications.	No proactive Push or In-App messages received.
Registered for push but Notification Permissions not granted	No Push messages. In-App messages show only if the user is actively on the app screen when triggered.
Registered and Notification Permissions Granted	Message appears in the device tray. In-App shows after tapping the tray notification or upon opening the app directly.
In-App Expiry Time	2 days from time of delivery.

Pausing In-App Messages

Existing API to pause in-app support messages - PauseDisplayOfInAppNotification - affects Proactive Engagement messages as well. 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.

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.

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. The configuration data is exactly same as we would expect in other APIs like showConversationWithConfig: or showFAQsWithConfig:.

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.

Implement public protocol HelpshiftProactiveAPIConfigCollectorDelegate and call setProactiveAPIConfigCollectorDelegate: 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 showConversationWithConfig: or showFAQsWithConfig:. 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 HelpshiftProactiveAPIConfigCollectorDelegate protocol and how to add user specific configurations using getAPIConfig method -

 public class MyGameControl : MonoBehaviour
  {
      private HelpshiftSdk help;

      void Awake()
      {
          help = HelpshiftSdk.GetInstance();
          help.Install( .. );
          ..
          ..
          help.SetHelpshiftProactiveConfigCollector(new ProactiveConfigCollector());
      }
  }

// initialise proactiveConfig collector

   public class ProactiveConfigCollector : IHelpshiftProactiveAPIConfigCollector
    {
        public Dictionary<string, object> getLocalApiConfig()
        {
            Dictionary<string, object> proactiveConfig = new Dictionary<string, object>();
            proactiveConfig.Add("initialUserMessage", "Hi there!");
            proactiveConfig.Add("fullPrivacy", true);
            proactiveConfig.Add("tags", new string[] { "vip", "payment", "blocked", "renewal" });
            ..
            ..
            return proactiveConfig;
        }
    }

Note

• You need to call this API after Install API and before handleBackgroundNotificationClick:withCompletionHandler:
• The "customIssueFields" key has been deprecated. We strongly recommend transitioning to using the "cifs" key as the preferred method for passing custom issue fields.