Looking for older SDK 3.X docs? Click here →

Notifications

Configure Push and In-app 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 {
...
    if([[[UIDevice currentDevice] systemVersion] floatValue] >= 8.0) {
        UIUserNotificationType notificationType = UIUserNotificationTypeBadge | UIUserNotificationTypeAlert;
        UIUserNotificationSettings *notificationSettings = [UIUserNotificationSettings settingsForTypes:notificationType categories:nil];
        [[UIApplication sharedApplication] registerUserNotificationSettings:notificationSettings];
        [[UIApplication sharedApplication] registerForRemoteNotifications];

    } else {
        [[UIApplication sharedApplication] registerForRemoteNotificationTypes:(UIRemoteNotificationTypeAlert | UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound)];
    }
...
}

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

You can configure this in 4 simple steps:

Setup your application with Apple and enable Push notifications.

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

helpshift-push-notifications.png

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.

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.

password-expiry.png

Configure the Helpshift iOS SDK to handle notifications

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 {
    [HelpshiftCore registerDeviceToken:deviceToken];
}

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    HelpshiftCore.registerDeviceToken(deviceToken)
}

When a push notification is received, the application delegate didReceiveRemoteNotification: is called. Additionally:

  • If the application was not in the foreground, and the user taps the push notification, this method is called again.
  • In cases where the app might have been killed by the user, and then they tap on a push notification, the application's didFinishLaunchingWithOptions: delegate is called.

In all of the above cases, developers should check the "origin" field of the notification dictionary and call handleRemoteNotification:isAppLaunch:withController: 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:

When receiving remote notifications when the app starts for the first time, or after being killed by the user:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    ...
    if(launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey]) {
        NSDictionary *userInfo = launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey];
        if([[userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
            [HelpshiftCore handleRemoteNotification:userInfo
                                        isAppLaunch:true
                                     withController:self.window.rootViewController];
        }
    } else if(launchOptions[UIApplicationLaunchOptionsLocalNotificationKey]) {
        [self application:application didReceiveLocalNotification:launchOptions[UIApplicationLaunchOptionsLocalNotificationKey]];
    }
    ...
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
{
    ...
    let notificationType: UIUserNotificationType = [UIUserNotificationType.badge, UIUserNotificationType.alert]
    let notificationSettings = UIUserNotificationSettings(types: notificationType, categories: nil)

    UIApplication.shared.registerUserNotificationSettings(notificationSettings)
    UIApplication.shared.registerForRemoteNotifications()

    if launchOptions != nil {
        let userInfo = launchOptions?[UIApplicationLaunchOptionsKey.remoteNotification] as? NSDictionary
        if userInfo != nil && (userInfo?["origin"] as! NSString).isEqual(to: "helpshift") {
            HelpshiftCore.handleRemoteNotification(userInfo as! [AnyHashable : Any], isAppLaunch: true, with: self.window?.rootViewController)
            }
        }
    ...
}

For the didReceiveRemoteNotification delegate -

- (void) application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    if([[userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
        [HelpshiftCore handleRemoteNotification:userInfo
                                isAppLaunch:false
                             withController:self.window.rootViewController];
    }
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
    if (userInfo["origin"] as! NSString).isEqual(to: "helpshift") {
        HelpshiftCore.handleRemoteNotification(userInfo, isAppLaunch: false, with: self.window?.rootViewController)
    }
}

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];
}

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

In-app notifications

Applicable to SDK version 2.4.0-rc-1 and above

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.

in-app-notification-badge-count-1.png

in-app-notification-badge-count-2.png

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
YES/NO
Default
YES

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

Example:

[HelpshiftCore installForApiKey:@"<API_KEY>"
                     domainName:@"<DOMAIN_NAME>"
                          appID:@"<APP_ID>"
                    withOptions:@{@"enableInAppNotification":@"NO"}];

Pausing In-app notifications

If you have enabled in-app notifications, use the API pauseDisplayOfInAppNotification: to pause/resume the notifications. When YES is passed to this method display of in-app notifications is paused even if they arrive. When you pass a NO, the in-app notifications start displaying.

Adding In-app notificatons to Notification Center

The notifications will be added to the notification center where the customer can click on them and get to the conversation view.

To enable this support, developers need to call the handleLocalNotification:withController: API in the application:didReceiveLocalNotification: delegate handler.

If the local notification is one added by the Helpshift SDK, the "origin" field in the userInfo dictionary of the local notification object will be "helpshift". For example:

- (void) application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification
{
    if ([[notification.userInfo objectForKey:@"origin"] isEqualToString:@"helpshift"]) {
        [HelpshiftCore handleLocalNotification:notification withController:[[UIApplication sharedApplication] keyWindow].rootViewController];
    }
}

func application(_ application: UIApplication, didReceive notification: UILocalNotification) {
    if (notification.userInfo?["origin"] as! NSString).isEqual(to: "helpshift") {
        HelpshiftCore.handleLocalNotification(notification, with:self.window?.rootViewController)
    }
}

Notification badges

If you want to show your user notifications for replies you send to the issues they posted, you can use notification counts provided by Helpshift SDK that gives you the total number of unread messages and display it as a badge. You can get notification counts asynchronously by implementing the HelpshiftDelegate in your respective .h and .m files. Notifications are typically displayed as badges inside your app where a user invokes the help section. These badges can be displayed anywhere in your app's interface to tell the user that they have unread replies/messages from you. For example to display a badge on a view (lets say its called yourView which can set its textLabel) while you are polling for notifications using:

[HelpshiftSupport getNotificationCountFromRemote:YES];

You can implement something like the following in the notification count delegate method:

- (void) didReceiveNotificationCount:(NSInteger)count {
    dispatch_async(dispatch_get_main_queue(), ^{
        [yourView setTextLabel:[NSString stringWithFormat:@"%d",count];
    });
}

Similarly for a UITabBarItem in the notification count delegate method you can implement something like:

- (void) didReceiveNotificationCount:(NSInteger)count {
    dispatch_async(dispatch_get_main_queue(), ^{
        tabBarItem.badgeValue = [NSString stringWithFormat:@"%d",count];
    });
}

These will update your view or UITabBarItem whenever a new notification arrives in the delegate method. The situation can vary depending upon your app UI. Showing notification counts at appropriate places would help you draw in your users so that you can engage them more in conversations and hence solve their problems better. To directly display a notification count to your users, you can call getNotificationCountFromRemote :

NSInteger count = [HelpshiftSupport getNotificationCountFromRemote:NO]

To directly retrieve the count, and then show it like:

[yourView setTextLabel:[NSString stringWithFormat:@"%d",count];

or

tabBarItem.badgeValue = [NSString stringWithFormat:@"%d",count];

Delegates and Notification Count

  • Use the following method to set the delegate, where self is the object implementing the delegate. [[HelpshiftSupport sharedInstance] setDelegate:self];

  • If you now call the method [HelpshiftSupport getNotificationCountFromRemote:YES]; it will return a notification count in the didReceiveNotificationCount:(NSInteger)count delegate method.

  • If you want to retrieve the current notification count synchronously, you can call the same method with the parameter set to false, i.e NSInteger count = [HelpshiftSupport getNotificationCountFromRemote:NO];.

  • Notification badge count on application icon does not include the count of unread messages from campaigns inbox.

Troubleshooting

If you are having issues with getting notifications to work, head over to the Troubleshooting section for further information.