Troubleshooting iOS chat push notifications in Sendbird

Introduction

Push notifications are essential for sending critical messages to users and encouraging them to return to your mobile app. They deliver essential information and updates, increasing user engagement with your app. Please see our guide to mobile push notifications for more information about push notifications, their benefits, and how they can be used.

This guide will explain how push notifications work with Sendbird Chat and how to troubleshoot issues when they occur. As part of this, we will cover some basic tests to diagnose problems and suggest solutions. This is guide is for the iOS SDK and does not include iOS support for the JavaScript SDK.

To streamline push notifications testing and debugging, please check out our push notifications tester tool tutorial.

Let’s start with a few preliminary checks. ✅

Preliminary checks

Please verify that:

1. You have enabled push notifications on the Sendbird dashboard for APNs (Apple Push Notification service). Ensure that:
   • Your .p12 certificate is not expired.
   • Your .p12 certificate is correctly mapped to your development app or to your production app. When the certificate is uploaded, you must specify ‘development’ or ‘production’ as the certificate type.
     • The production certificate should be an “Apple Push Notification service SSL (Sandbox & Production)” certificate.
     • The development certificate can be either an “Apple Push Notification service SSL (Sandbox)” or “Apple Push Notification service SSL (Sandbox & Production)” certificate.

   Please note: you will need a ‘production’ certificate to test push notifications on TestFlight apps (These may include development apps released to TestFlight).

2. Your app has registered a push token for your user.
   The top issue faced by most app developers is that the push token for the user is not correctly registered or is no longer valid. To check the user’s push token on the Sendbird Dashboard, go to the “Dashboard” > “Users” section, select your user, and look for “Push Token” in the “Chat” section.
3. You are testing on a physical device, not the Xcode simulator.
4. You are testing push notifications in Group Channels (push notifications are not supported in Open Channels).
5. Your app does not disconnect() the user and unregisters the device token when the app goes into the background. Using disconnect() and unregistering the token is mainly recommended for when the user logs out of the device and no longer needs to receive notifications.
6. Your device has the app running in the background or closed in order to receive remote notifications that come from APNs via Sendbird. Please note the push notification settings on the app dashboard in this case:
   • With the ‘Send as long as one device is offline’ setting, any device in the background can receive the remoted notification.
   • With the ‘Send when all devices are offline’ setting, every single device running the app with the connected user must be running in the background or closed.
7. You are testing with the latest version of the Sendbird iOS SDK.
   • Specifically for iOS 13 support, Sendbird iOS SDK v3.0.150 or greater is required for building your app. The reason for this is that the release of Xcode 11, which was released alongside iOS 13, changed a common way that apps and libraries were using to get a push token for the device. iOS 13 users will not be able to subscribe to notifications from your app on a lower SDK version than v3.0.150.

If you/your development team confirms all of the above and any problems persist, please don’t hesitate to get in touch with the Sendbird support on your Sendbird app dashboard (Dashboard > Your Organization Name (at the top right) > Contact Us). In your description of the issue, please share the app ID, iOS Chat SDK version number, user ID and device token for that user, channel_url, and a timestamp of the last push notification test performed so we can investigate further. Screenshots, GIFs or videos of the issue can also help in an investigation.

Best practices for device tokens

Sendbird follows Apple’s guideline to “register your app and receive your device token each time your app launches”. So, we recommend registering your user’s device token to Sendbird every single time the user connects to Sendbird.

The list below specifies when the token may be updated on the device by APNs:

1. The app is restored on a new device
2. The user uninstalls/reinstalls the app
3. The user clears app data.

Now let’s talk about how to troubleshoot common issues.

Troubleshooting by case

1. User is not offline
   It’s easiest to test push notifications when your user is offline and the app is not in the foreground on any device. Check that user’s offline status in the Users section of the Sendbird dashboard.
2. Device token issues
   Ensure the user has a device token registered. To check the user’s push token on the Sendbird dashboard, go to the Users section under your app. Select your user and look for Push Token in the Chat section. If the user has multiple device tokens (as seen on the platform API here), please try to unregister all of the user’s current device tokens by calling the platform API. Add a new token by calling the platform API or by running the app again. This registers the user’s device token via the SDK. Check the Sendbird dashboard for the user’s latest token.
3. Specific user cannot receive a push notification
   Check that the test user does not have push notifications disabled. Our platform API makes it easy to:
   • Check the user’s push preferences through the platform API.
   • Check the is_push_enabled channel property of your test channel when you fetch the list of the user’s group channels through our platform API. If is_push_enabled is ‘false’, update the user’s push preferences for a specific channel to see that the test channel where the push notification should be received is a group channel and does not have push notifications disabled for this user.
4. User sometimes receives a push
   Check for local or remote notification support. If your app is explicitly generating notifications locally while the app is in the foreground, these local notifications are NOT triggered by APNs as push notifications sent by Sendbird. Your application may be listening to the message received event delegate in the app and triggering a local notification that looks like a push notification. Check that the notification payload from Sendbird is handled by the application:didReceiveRemoteNotification:fetchCompletionHandler: method. The channel:didReceiveMessage: is an event handler that will be fired for messages received while the user is online and may trigger local notifications only.
5. User can receive notifications on one device, but not another (multi-device support)
   One device may receive a push notification for the user while another does not. Ensure you have selected the ‘Send to devices both offline and online’ setting on your Sendbird dashboard > Settings > Notifications.
   
6. Cannot upload APNs push certificate to Sendbird
   If you have problems uploading the .p12 certificate to Sendbird, you may receive an error message, such as:
   
   • From the Sendbird dashboard:

   {"CREATE Push Configuration" failed.}

   • From the Platform API:

   {"message": "\"CREATE Push Configuration\" failed.", "code": 500901, "error": true
   

   This may be caused due to uploading an invalid certificate. Please make sure you are uploading a valid certificate to support push notifications. Check that you are uploading an ‘Apple Push Notification service SSL’ certificate, not an ‘Apple Distribution’ certificate. To check the certificate, open it in ‘Keychain Access’. A valid certificate should say ‘Apple Push Services’ in the name. You can also right-click on the certificate in Keychain Access and select ‘Get Info’ to see more information on the certificate. If the certificate does not say ‘Apple Push Services’ in the Common Name or does not say ‘Apple Push Service Client’ in an extension, it may not be a valid push certificate.
   
   
   

7. Your app requires special certificate options
   

   Your application may be relying on silent background updates via push notifications or a modified push notification payload prior to displaying the notification.
   
   a. Content-available: Determines for your client app whether to perform a silent background update on a user’s device. For more information, see the Apple Developer Documentation’s Pushing Background Updates to Your App. (Default: false). Sendbird recommends NOT setting content-available to ‘true’ for your push notifications because they can be throttled by APNs and disrupt the delivery of push notification messages received in your app.
   
   b. Mutable-content: Determines for your client app whether or not to modify the payload of a push notification before it is displayed on a user’s device. For more information, see the Apple Developer Documentation’s Modifying Content in Newly Delivered Notifications. (Default: false)
   
   c. Check that your push notification certificate has the ‘Content available’ or ‘Mutable content’ options selected. To enable these settings on your Sendbird app, go to dashboard > Settings > Notifications > APNs > select the three dots next to your iOS certificate > ‘Edit’.
   

   

   Alternatively, update these options through the platform API. (Note: The ‘provider_id’ required by the update endpoint is the same as the push_configuration ID. You can see a list of all their push_configurations and filter the ‘push_type’ by ‘apns’)

Testing

Test to determine if your Sendbird application can receive notifications from Sendbird’s server.

1. Download Sendbird’s iOS sample app and change the application ID to your Sendbird app ID.
2. Change the bundle ID to your app’s bundle ID that matches your certificate uploaded to the Sendbird dashboard.
3. Sign in as a user (user A).
4. Quit the app. Ensure that the app is not in the background and that user A is offline.
5. On another device, send a message to the user (user A) from another user (user B). Or, test sending to user A’s device with the push notification tester tool. Did the first user (user A) receive the notification? If yes, then push notifications can be sent by the Sendbird server to your application. In your application, check that your application is registering a device token for your user and that your application implements the application:didReceiveRemoteNotification:fetchCompletionHandler: method.

Development testing with a production app user

It’s possible to test push notifications in development against a production app user.

1. Start with a production app user ‘Bob’ and ensure ‘Bob’ is offline.
2. Under the current production app, device token A is associated with the production certificate for ‘Bob’.
3. Upload the development certificate to the Sendbird dashboard.
4. Run the app in Xcode on your own test device to test with the development certificate. Connect as user ‘Bob’ and ensure your application registers a new device token B for the development certificate.
5. Sendbird tries to send a push notification to device token B for the production and development certificates. Only the development certificate succeeds, and now device token B is associated with the development certificate.
6. User ‘Bob’ will still have device token A associated with the production certificate unless that token is unregistered or a new token is registered for Bob’s device.

Other notes

1. Language Translation: Push Notifications can be translated to other languages when message translation is enabled for your application by specifying the user’s preferred_languages through the platform API or adding these languages through the SDK.

Testing Tools

Pusher
https://github.com/noodlewerk/NWPusher
Test with your APNs push notification certificate outside of Sendbird to see if it works with the user’s registered device token. Please note that your user’s device token may be different in development if the push notification certificate is an Apple Development iOS Push Services certificate instead of an Apple Push Services certificate.

Sendbird push notifications tester

The push notifications tester allows you to send a test push notification to any registered user’s device in your application. You can send a test push notification to a user on an iPhone, Android, or Huawei device with full support for Apple Push Notification service (APNs), Firebase Cloud Messaging (FCM), or HUAWEI Mobile Services (HMS). For a complete review of the tool, check out our guide.

Conclusion

We have discussed preliminary push notifications checks, best practices for device tokens, and how to troubleshoot push notifications in various scenarios. Push notification debugging can be complex, but between this guide and our new tester tool, you will be self-reliant. As always, if you have questions, please contact us via our Sendbird community or through your support plan.

If you are interested in deploying more notification capabilities beyond mobile push, consider evaluating Sendbird Business Messaging, Sendbird's omnichannel messaging solution spanning SMS, WhatsApp, and in-app notifications. 

Until next time, happy push notification building! 👩‍💻