Rate this page:

iOS SDK (IP messaging)

Voximplant push notifications for messaging in iOS apps are based on Apple Push Notifications. With the help of notifications, a device can be awakened and an application can be started when a message arrives.

The following tutorial explains the code needed to handle push notifications and describes additional steps that should be performed to have a working push notifications solution for your mobile applications.

Please note
  1. The ability of APNs to deliver remote notifications to a nonrunning app requires the app to have been launched at least once.
  2. On an iOS device, if a user force-quits your app using the app multitasking UI, the app does not receive remote notifications until the user relaunches it.

Configure your iOS project

  1. Open the project in XCode.

  2. Switch to the Project Navigator and click on the project.

  3. Go to the Signing & Capabilities tab at the top panel. Check the Adding capabilities to your App Apple guide for more details.

  4. Enable Push Notifications and these two Background Modes: "Background fetch" and "Remote notifications".

Add certificates to the Voximplant Cloud

  1. Generate an Apple Push Notification service SSL (Sandbox & Production) certificate following the instruction.

  2. Install the generated certificate to your Mac by double-clicking the downloaded file and import it into the OSX Keychain of your Mac.

  3. In the Keychain interface, right-click on the imported certificate and export it as .p12 file with a password.

  4. Log in to the Voximplant control panel.

  5. Go to your application, then switch to the Push Certificates tab.

  6. Click on the Add Certificate in the upper right corner.

  7. In the Certificate for list, select APPLE.

  8. Click on Choose File and upload the .p12 file.

  9. Enter password you have used while generating a file from your Keychain interface.

  10. Select Production or Development mode for the certificate.

  11. Click the Add button.

Production vs Development mode

Be careful while selecting the certificate mode as the push notification delivery depends on it. Use Production mode only for the applications that are already released to the App Store or TestFlight. Use Development mode only with application builds built locally on the developer’s machines for debug purposes.

The Voximplant Platform supports sending push notifications to several iOS applications with different package names within the same Voximplant application.

If it is required to add several APPLE certificates to the same Voximplant application, you have to set the application bundle name while adding the certificate.

Please note

If a bundle name is specified with a certificate, you must set the same bundle name when initializing the SDK.

Initialize SDK with the package name

Initialize SDK with the package name

Tip

The Voximplant Control Panel allows you to add only one certificate of one type. If you are developing an application and need to test push notifications in both Debug and Release modes, add the same APPLE certificate with your application bundle + specific suffixes, for example, “.dev”, “.prod”.

The Voximplant Cloud does not validate the bundle id, we use this parameter here only to identify the certificate needed to send a push notification. So, you don’t need to change the real bundle id, but only “mark” it for the Voximplant Cloud.

Do not forget to initialize the SDK correctly for Debug and Release configuration and set the suffix of the bundle id depending on the configuration.

Provide a token to the Voximplant cloud

The Voximplant Cloud requires a device token to send a push notification.

The token should be requested from the UIApplication object. We recommend that you ask the user for permission to show a local notification before requesting an APNs token.

Once the token is received, it should be registered via VIClient.registerIMPushNotificationsToken(_:completion:) API.

Receiving a token

Receiving a token

VIClient.registerIMPushNotificationsToken(_:completion:) API may be called in any VIClient state (VIClientState), however, the token will be registered only after the client logs in.

Register the token in these cases:

  • Token has been updated by <provider>.

  • Some other Voximplant user has logged in on the device.

Subscribe for IM push notifications

The Voximplant Cloud can send push notifications for IP messaging when one of the following events occurs:

By default, push notifications are not sent. To enable them for a user, it is required to call VIMessenger.managePushNotifications(_:completion:) API and indicate preferred VIMessengerNotification types. The client should log in to the Voximplant Cloud for the subscription to be successful.

Enable IM push notifications

Enable IM push notifications

Handle push notifications

The application receives the payload of a remote notification through its app delegate. When a remote notification arrives, the system delivers the notification payload to the application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method of the app delegate.

Once a push notification is received, use VIMessengerPushNotificationProcessing to get a VIMessageEvent and therefore all data and process it as VIMessengerDelegate.messenger(_:didSendMessage:) or VIMessengerDelegate.messenger(_:didEditMessage:) event.

To ensure that this is a Voximplant IM push notification, check the “voximplant_im” signature in the push data.

The push notification payload contains the following information:

  • New or edited message UUID

  • Conversation UUID the message belongs to

  • Message text

  • Initiator’s user id

  • sequential number of the event in the conversation

Handling push notifications

Handling push notifications

Please note that VIMessengerPushNotificationProcessing interface only converts the push payload to an VIMessageEvent object with no modifications of it or updates of other VIMessenger objects instances.