Push notifications in Kit Chat for iOS

Voximplant Kit sends alert push notifications about new inbound chat messages. Notifications are delivered through APNs and displayed automatically by the system. The application does not need to create notifications manually.

This article describes how to register a push token, configure notification handling in an active application, change notification content, and test notifications.

Example of a payload received from Voximplant Kit:

To let the application receive notifications, request the user's permission to display notifications and register the APNs token in Voximplant Kit.

Requesting permission and getting a token

Registering a token in the SDK

The isDevelopment parameter value depends on the application build type:

To stop receiving notifications, use VIKitChatUI.unregisterPushToken(_:isDevelopment:completion:) in the same way.

Managing notifications in an active application

When the application is active, iOS does not display push notifications by default if the UNUserNotificationCenterDelegate delegate is not assigned or the userNotificationCenter(_:willPresent:withCompletionHandler:) method is not implemented.

If notifications are needed in an active application, but not on all screens, assign the UNUserNotificationCenter delegate and define the logic in the userNotificationCenter(_:willPresent:withCompletionHandler:) method.

In the example below, notifications are displayed in all cases except when VIKitChatViewController is displayed on the screen:

The push notification payload from Voximplant Kit contains the voximplant_im key. You can use this key for filtering if the application receives push notifications from different sources.

Notification customization is performed through Notification Service Extension. The extension receives a push notification before iOS shows the notification to the user and lets you change the displayed title, text, sound, badge, or other parameters.

Available customization options:

To set up notification customization, create a separate target in Xcode: File > New > Target > Notification Service Extension. Then add the required customization logic to this extension.

Notification Service Extension limitations:

In the standard case, Notification Service Extension receives a push notification from Voximplant Kit and changes the notification content, for example, replaces the text:

Localization

To localize notification text, use NSLocalizedString. It returns a localized value from the .strings file of the Notification Service Extension target based on the device language:

Disabling sound

By default, the push notification from Voximplant Kit specifies a sound. To show the notification without sound, use the following code:

Badge management

Badge is a numeric counter on the application icon. To work with badge between Notification Service Extension and the application, a shared App Group is required:

Using payload data

Data from the push notification payload can be used to change the notification the user will see. In the example below, if attachments are present (with_attachments: 1), an icon is added to the notification:

Running asynchronous code

Notification Service Extension supports asynchronous code execution, for example, network requests. In the example below, an image is downloaded to be displayed in the notification:

In this implementation example, if the request is not completed within approximately 30 seconds, serviceExtensionTimeWillExpire() passes bestAttemptContent with unmodified content. The user will see the notification without the image.

Before integration, we recommend testing push notifications using Apple Push Notifications Console. For details, see the documentation. The console lets you send an APNs push with a specified payload to a device using its token.

This helps check the application behavior with the current codebase when new push notifications are received and understand whether changes are required.

For testing, you can use the following payload. If necessary, replace the values with test data:

In SDK versions below 1.6.0, SDK APIs were used for notification customization. Starting with version 1.6.0, these APIs are deprecated.

When updating, do the following:

1. Remove calls to configureChatNotification(configuration:) and handlePushNotification(_:completion:).

2. Remove the use of VINotificationConfiguration.

3. Remove chat-related push notification handling in application(_:didReceiveRemoteNotification:fetchCompletionHandler:).

4. Replace VIPushNotificationError with VIPushTokenError.

5. For notification customization, use Notification Service Extension as described above.