Push notifications are essential for sending critical messages to users and encouraging them to return to your mobile app. Push notifications are important because they deliver important information, updates, and increase 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.
To streamline push notifications testing and debugging, please check out our push notifications tester tool tutorial.
Let’s start with a few preliminary checks. ✅
Please verify that:
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).
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.
You are testing on a physical device, not the Xcode simulator.
You are testing push notifications in Group Channels (push notifications are not supported in Open Channels).
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.
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.
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:
The app is restored on a new device
The user uninstalls/reinstalls the app
The user clears app data.
Now let’s talk about how to troubleshoot common issues.
Troubleshooting by case
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.
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.
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 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.
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.
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.
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:
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.
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.
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.
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)
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’.
Test to determine if your Sendbird application can receive notifications from Sendbird’s server.
Download Sendbird’s iOS sample app and change the application ID to your Sendbird app ID.
Change the bundle ID to your app’s bundle ID that matches your certificate uploaded to the Sendbird dashboard.
Sign in as a user (user A).
Quit the app. Ensure that the app is not in the background and that user A is offline.
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.
Start with a production app user ‘Bob’ and ensure ‘Bob’ is offline.
Under the current production app, device token A is associated with the production certificate for ‘Bob’.
Upload the development certificate to the Sendbird dashboard.
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.
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.
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.
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.
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.
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 feel free to reach out to us via our Sendbird community or through your support plan.
Until next time, happy push notification building! 👩💻
Subscribe to our Monthly Developer Digest
Stay up-to-date on the latest technical content from Sendbird.