Notifications iOS

Configure Push and In-app notifications.

Note

All the public APIs in the SDK should be called after initializing the SDK via HelpshiftSdk.install() API

Note

An easy way to setup push notifications is to uncomment relevant code in the HsUnityAppController.mm file. The class HsUnityAppController implements the AppDelegateListener and provides relevant delegate methods needed to get started with push notifications.

Configure push notifications via Helpshift

Notifications can be sent to your users when you reply to an issue submitted by them. In addition to the expected Push Notification behavior on iOS, you can customize your notifications to display a numbered badge on your App icon or play a sound alert when a notification is received.

If your app does not already use push, you will need to enable push for your app. To enable push notification in your application you need to add APNS registration code to your AppDelegate's application:didFinishLaunchingWithOptions: method:

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    UNUserNotificationCenter *center = [UNUserNotificationCenter currentNotificationCenter];
    center.delegate = self;
    [center requestAuthorizationWithOptions:(UNAuthorizationOptionBadge     UNAuthorizationOptionSound | UNAuthorizationOptionAlert)
                                                                     completionHandler:^(BOOL granted, NSError *_Nullable error) {
                            ...
                        }];
    [UIApplication sharedApplication registerForRemoteNotifications];
    ...
}

Configure Helpshift's push notification service in the Helpshift admin interface

To enable the Helpshift system to send push notifications to your users you will have to add iOS as a platform in your app (if you have not added already). And then click on the push notifications option.

In order to send push notifications to all iOS mobile apps and games, you need to establish an authenticated connection with the Apple Push Notification Servers (APNs). There are two methods you can use to authenticate:

1. The newer token-based method (.p8)
2. The older certificate-based method (.p12)

Token-based method (.p8)

The token-based method is faster because it offers a stateless way to communicate with APNs. It doesn't require APNs to look up the certificate or any other information related to the provider server.

We now support the newer token-based .p8 key method, which allows you to send notifications to all your iOS apps and games using a single key. You can generate your .p8 key through your Apple developer account, as explained here.

Here are the steps to configure iOS push notifications using .p8 keys:

1. Go to Settings, then navigate to the APP SETTINGS section to choose the app you want to configure.

2. On the App settings page, click on the CONFIGURE option next to In-app SDK.

3. On the In-app SDK Configuration page, navigate to the Push Notification section.

4. Enable the toggle for Apple Push Notification Service if not enabled. The app selects the p8 key authentication type by default when you enable the toggle for the first time.

5. Upload the p8 key and fill in all the required details.

6. Select the APNs push mode (Development/Production).

7. Click on Save & Publish to save the changes.

Note

You can also switch from .p8 key to .p12 certificate method if required, by selecting .p12 in Authentication type and filling the details.

Certificate-based method (.p12)

You need to generate certificates for APNS on Apple's portal that you can later provide to Helpshift. This lets Helpshift send push notifications to your users. Apple has moved away from old type of certificates to Apple Push Notification service SSL. There is another option to create Apple Push Notification Authentication Key, but Helpshift does not support this option yet. It's also possible that you still have the old type of certificate that has not yet expired, this is also supported by Helpshift.

Apple provides two variations of Apple Push Notification service SSL

• Apple Push Notification service SSL (Sandbox)
• Apple Push Notification service SSL (Sandbox & Production)

After creating your certificate, download it. Double click on it to import it to the Keychain Access application. In the Keychain Access application, right click on the certificate that was just added, and click export it in .p12 format. Please provide a password while exporting the certificate since we do not accept empty passwords. (Note that if your development private key is not present in Keychain Access, you will not be able to export it in .p12 format.)

After export, login and upload the .p12 file in your app in the Helpshift admin panel. Provide the same password you used while exporting to .p12 format.

Please note that you need to use the same bundle identifier in the app as the one you used to create the APNS certificate.

You can configure whether to send a badge or not, and sound alerts if you provided custom sounds bundled with your app to handle notifications. Save it and you're all set.

Development (Sandbox) mode vs. Production mode

When you build and run your app from Xcode, it is in development (Sandbox) mode. To test push notifications from Helpshift in this mode make sure you choose 'Development Mode' while uploading either of the above two certificate types.

When you publish your app and download from App Store, your app is in Production mode. To test push notifications from Helpshift in production mode make sure you choose 'Production Mode' while uploading a certificate of 'Apple Push Notification service SSL (Sandbox & Production)' type. Sandbox mode certificate will not work on a production environment.

We do not support using the same certificate for both sandbox and production apps. In these cases we recommend you create two separate apps on our dashboard, one in 'Production mode' and the other in 'Development mode'. While testing please use the credentials of the developement mode app. When you are ready to publish, please replace the credentials with those of the production level app.

Note

Your Push Certificate has an expiry date, as indicated in the below screenshot. Helpshift will not send you a reminder when your Push Certificate expires, so please make sure that your developer keeps a tab on the expiry date to reupload the Push Certificate.

Configure the Helpshift iOS SDK to handle notifications

Note

When push is not configured, Helpshift SDK shows out-of-the-box "in-app notifications" for every message sent by Agents/Bots. You should call registerDeviceToken API only after you have configured the Helpshift dashboard for push notifications. Calling the registerDeviceToken API without configuring the Helpshift dashboard will stop showing out-of-the-box "in-app notifications" for the end users.

For Helpshift SDK to work with the Helpshift push notification service you will need to invoke the registerDeviceToken: api call inside the application delegate method application:didRegisterForRemoteNotificationsWithDeviceToken:

In your app delegate file it will look something like this:

- (void) application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [Helpshift registerDeviceToken:deviceToken];
}

To respond to the delivery of notifications, you must implement a delegate for the shared UNUserNotificationCenter object. Your delegate object must conform to the UNUserNotificationCenterDelegate protocol, which the notification center uses to deliver notification information to your app:

1. If a notification arrives while your app is in the foreground, UNUserNotificationCenterDelegate's willPresentNotification: is called.
2. The system does not call the userNotificationCenter:willPresentNotification:withCompletionHandler: method when your app is in the background or is not running. In those cases, the system alerts the user according to the information in the notification itself. When the user selects an action from the notification interface, the system notifies your app of the user's choice. To receive responses, your delegate object must implement the userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: method.

In all of the above cases, you should check the "origin" field of the notification dictionary and call handleNotificationWithUserInfoDictionary:isAppLaunch: API if the origin of the notification is "helpshift". The Helpshift SDK will check Issues for which the notifications were received and will launch the Conversation screen for those Issues automatically. The isAppLaunch boolean flag here is used to distinguish between an active or backgrounded app vs. an app that was killed by the user. In the latter case, this flag should be set to true.

Example usage:

For the userNotificationCenter:willPresentNotification:withCompletionHandler: delegate -

- (void) userNotificationCenter:(UNUserNotificationCenter *)center
  willPresentNotification:(UNNotification *)notification
  withCompletionHandler:(void (^)(UNNotificationPresentationOptions options))completionHandler {
  if([[notification.request.content.userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
    [Helpshift handleNotificationWithUserInfoDictionary:notification.request.content.userInfo
                                                isAppLaunch:false];
    completionHandler(UNNotificationPresentationOptionNone);
  } else {
    // Handle foreground notifications other than Helpshift ones.
  }
}

For the userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: delegate -

- (void) userNotificationCenter:(UNUserNotificationCenter *)center
 didReceiveNotificationResponse:(UNNotificationResponse *)response
          withCompletionHandler:(void (^)(void))completionHandler {
    if([response.notification.request.content.userInfo[@"origin"] isEqualToString:@"helpshift"]) {
        [Helpshift handleNotificationWithUserInfoDictionary:response.notification.request.content.userInfo
                                                isAppLaunch:YES];
    } else {
        // Handle push notifications other than Helpshift ones.
    }
    completionHandler();
}

Badge count

If you need to handle badge reset in the application icon, you can do something like below in the applicationDidBecomeActive: delegate method:

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [[UIApplication sharedApplication] setApplicationIconBadgeNumber:0];
}

Note

To test Push Notifications for an app that is already in production please refer this.

In-app notifications

In-app notifications are similar to Apple's push notification banners. Unlike push notifications, they appear within your app when it is in use by the user.

These notifications are sent when an agent replies to a customer's issue. Your customers can click on these banners to go straight into the conversation screen.

Configuring In-app notifications

The Helpshift install call supports flags for configuring SDK behaviour. Currently we support one flag i.e enableInAppNotification.

Enabling/Disabling In-app notifications

Flag	enableInAppNotification
Values	true/false
Default	true

If you do not want the in-app notifications support provided by the Helpshift SDK, please set this flag to false. The default value of this flag is true i.e in-app notifications will be enabled.
Read more about in-app notifications in the Notifications section.

Example:

using Helpshift;

private HelpshiftSdk help;
this.help = HelpshiftSdk.GetInstance();
Dictionary<string, object> configMap = new Dictionary<string, object>();
configMap.Add(HelpshiftSdk.ENABLE_INAPP_NOTIFICATION, true);
help.Install(appId, domainName, configMap);

Pausing In-app notifications

If you have enabled in-app notifications, use the API PauseDisplayOfInAppNotification() to pause/resume the notifications. When true is passed to this method, display of in-app notifications is paused even if they arrive. When you pass false, the in-app notifications start displaying.

Example:

using Helpshift;

// Install call
private HelpshiftSdk help;
this.help = HelpshiftSdk.GetInstance();
Dictionary<string, object> configMap = new Dictionary<string, object>();
configMap.Add(HelpshiftSdk.ENABLE_INAPP_NOTIFICATION, true);
help.Install(appId, domainName, configMap);

// To temporarily pause in-app notifications
help.PauseDisplayOfInAppNotification(true);

// To resume showing the in-app notifications
help.PauseDisplayOfInAppNotification(false);

Showing notification count when replies are sent to the user

To fetch unread messages count from the server you can call Helpshift.RequestUnreadMessageCount(shouldFetchFromServer) API. This API will return unread messages count via delegate. Based on the value of shouldFetchFromServer, the locally stored count will be returned if shouldFetchFromServer is false else from the server by fetching remotely when shouldFetchFromServer is true. An example use of this count is to update the badge count to indicate unread messsages. Please note that before calling this method, you need to set the listener for Helpshift events by calling the Helpshift.SetHelpshiftEventsListener(eventsListener) API.

// Requesting unread count
private void RequestUnreadCount()
{
    Helpshift.RequestUnreadMessageCount(true);
}

When you call this API, you receive the unread count in your event listener which implements IHelpshiftEventsListener. Following is an example implementation

public class HSEventsListener : IHelpshiftEventsListener
{
    // ...
    public void HandleHelpshiftEvent(string eventName, Dictionary<string, object> eventData)
    {
      if(eventName.Equals(HelpshiftEvent.RECEIVED_UNREAD_MESSAGE_COUNT))
      {
        Debug.Log("Unread count: " + eventData[HelpshiftEvent.DATA_MESSAGE_COUNT]);
        Debug.Log("Is Unread count from cache: " + eventData[HelpshiftEvent.DATA_MESSAGE_COUNT_FROM_CACHE]);

        // Do something with the unread count here, for example, update the badge count.
      }
    }
    //...
}

• The notification count is fetched via this API from the SDK cache and Helpshift's servers (indicated by the value of fromCache in the example above). However, the count from Helpshift’s servers is rate limited and it returns the value only if a subsequent call is made to the API, after the reset timeout or when the user just closes the chat screen (whichever is earlier). For an active issue, the reset timeout is 1 minute and 5 minutes for inactive issues.