Troubleshooting Push Notifications


This article provides tips for troubleshooting common issues encountered with push notifications.

Expected behavior

When a user opens the app from a push notification, Swrve automatically sends a push engagement event. It is important that Swrve receives this engagement event to accurately track how many users have engaged with a particular notification. Swrve needs to receive the push engaged event in the following scenarios:

  • When the app is completely closed, that is, swiped away from the list of open apps.
  • When the app is in the background, that is, still running but inactive.

To check that the push engaged event was received, review the QA User Logging screen when sending a test push.

Note that if you send more than one test push while the app is open in the same session, you will only see the push engaged event for the first push. This is by design, to prevent engagement being tracked more than once for identical push notifications in the same session.

Push notifications debugging

The best way to debug push notifications is to send a message via our Push API to one of the QA devices from the command line. For detailed information about how to make calls to the Swrve Push API, see the Swrve Push API guide.

Once you've created a push API campaign in Swrve, open a terminal window and copy the cURL request from the campaign.

Note: Remember to start with a new QA device, or you might be trying to send to an old install of the app, or worse, another user!

Common issues

Unable to send a test push to QA device

Swrve enables you to send a test push notification via the Integration Settings screen, under the Settings menu. If your device is not available to select from the Select QA device list, then a push token has not been received for that QA device.

  • Ensure that you have followed the complete instructions from one of the below articles to set up the Google server key or the Apple push certificate:
  • Check that you have enabled push in the Swrve SDK. We provide example code for both Android and iOS in our platform-specific integration guides.
  • Check that Swrve has received the push token:
    • From the Settings menu, select QA Devices and check if push has been enabled for the device. In the Settings column, a green checkmark should be displayed next to Apple Push enabled or Google Push enabled.
    • On the QA Devices screen, in the row for the selected device, select Logging to view the QA User Logging screen (ensure you have the correct QA device). Inspect the raw JSON for the user update event that is sent when the app is opened and look for the swrve.gcm_token for Google or swrve.ios_token for Apple.

Remote and silent push expected behavior

This section explains how to understand, when sending remote push notifications to a device, the expected behavior of the device when the respective app is in different states and the differences between the iOS and Google/Android environments.

Notification types:

  • Remote notification (visual)
  • Silent notification (data)

App states:

  • In foreground
  • In background
  • Hard-closed
  • Force-stopped (Android only)
Platform & Type Foreground Background Hard-closed Force-stopped (Android)
Android Visual YES YES YES NO
Android Data YES YES YES NO

Push permission properties

There are two separate user properties used to track push permissions—one for iOS and one for Android.


User property: swrve.permission.ios.push_notifications

Possible values:

  • authorized - user has accepted push permission
  • denied - user has denied push permission
  • unknown - user has not yet been asked for push permission


User property: swrve.permission.notifications_enabled

Possible values:

  • true - default value when user installs the app
  • false - user has changed push permissions in the app settings to disable them

Push token update periods

Swrve performs several batch jobs throughout the day to find users with push device tokens registered and then loads any new device tokens into the push notification system. Therefore, it can take up to 10 hours for new users to be eligible to receive a push notification, depending on factors such as when the batch job is run and your company’s time zone. The number of users that appear in an audience estimate on the Audience block of the push campaign workflow is updated regularly to include new users. However, they may not be immediately available to send push notifications to, depending on the timing of the batch run (this does not apply to testing push notifications on QA devices).

Unable to receive a test push


The following are some reasons this issue occurs:

  • Incorrect server key or push certificate – Check that the server key or push certificate details are correct, and that you have a push token associated with your QA device by hovering the mouse over the green checkmark on the QA Devices screen.
  • Using another push service – Is another push service trying to display the message? If you have another push service running, for Android you need to make an additional change to the Manifest. For more information, see the heading Using Swrve Push Notifications with other providers in the Android integration guide.
  • Issue processing the intent – To debug the handling of the intent, you can examine adb logcat for errors. Check that the device is receiving the FCM message and if the broadcast receiver is being called.


There are some additional points to consider for iOS:

  • On iOS, push notifications are not shown on the device when the app is active. Try again when the app is completely closed or in the background.
  • A common issue is to upload the wrong certificate. There may be a mismatch between development and production, or the wrong certification may be uploaded. We require a valid .p12 file matching the environment to be uploaded. An adhoc or production build requires a production certificate.
  • Not agreeing to the push dialog when the push request appears on the device.
  • Not having the 'Allow Notifications' enabled in your Build Settings (Xcode). See image below.


  • Not having the 'Remote Notifications' enabled in your Build Settings (Xcode). See image below.Xcode_Remote_Notification.png

The app is not calling the push listener


For Android, ensure the following point has been addressed:

Cannot see push engagement event during QA

  • When the user selects a push notification, an engagement event is sent. The engagement event is displayed on the the QA User Logging screen for your device. The event looks like Swrve.Messages.Push-0.engaged. If you don’t see this event, the engagement reporting in Swrve will not work.
  • In older iOS Swrve SDK versions, code is required for both scenarios of when the app is running in the background and when it is completely closed. Ensure you have these code lines, or upgrade the SDK.
  • The Swrve SDK checks the last push notification received to compare against the notification the user has tapped. If this ID is the same, the push engagement event does not fire. This is particularly important in QA, as test pushes have the same ID (0). If you’re testing push notifications, close the app entirely and then send the test push. Next, test by closing the app, opening as normal, running the app in the background and sending another test push, to ensure the push engagement event is shown on the QA User Logging screen.

The device cannot receive a live push

Bear in mind the following points related to live push campaigns:

  • It can take a few hours from Swrve receiving the push token from the device to being able to send a live push notification, since our user databases are updated throughout the day. Try sending a test push in the meantime as this is available immediately.
  • If the app is uninstalled and reinstalled, the push token changes. If you have reinstalled the app, you may need to wait a few hours before being able to send a real push notification.
  • The device needs to have an internet connection to receive a push notification. Whether or not and how long a message is queued for depends on Apple and Google’s push services. Ultimately Swrve cannot guarantee that a device will receive the push once it has been delivered to Apple’s APNS or Google’s FCM.


For more details on the Firebase Cloud Messaging (FCM) service, see the Firebase Cloud Messaging guide.


Generally, iOS sees lower engagement rates than Android. Some common reasons for not receiving live pushes on Apple devices are:

  • Uploading the wrong type of push certificate.
  • Push notifications are not shown on the device when the app is active.
  • There are some device factors that prevent push notifications from being received, including the device being ‘face down’, in ‘quiet mode’, and so forth. Check that your device is configured to receive push notifications and they have not been disabled.
  • According to Apple documentation, APNS will queue up to one message if it was unable to deliver it; for example, if the device was offline. If any subsequent messages are sent, the previous messages are discarded. Check that your device is online when the push notification goes out.

For more information, see the Apple Push Notification Service guide.

Push notifications are already used in the app


You will need to make an additional change to the Manifest to ensure that your other push providers continue to work. For more information, see the Android integration guide.

Duplicate push notifications

If another push service is being used with Swrve, it could be trying to display the message. Refer to above section.

On Android this usually means that there's more than one third party push provider trying to consume the push notification. Follow our guide for Using Swrve push notifications with other providers.

Also, remember that Android has a much larger offline queue of notifications than iOS (just one as of 2019). This means if the device has been offline for awhile there's a good chance multiple notifications stored by Google will be downloaded to the device immediately.

I want to register the push token myself


By default, Swrve automatically registers the device token and triggers the push permission dialog. Swrve does this by swizzling the following methods that handle token registration:

  • didRegisterForRemoteNotificationsWithDeviceToken
  • didReceiveRemoteNotifications
  • didFailToRegisterForRemoteNotificationsWithError

If you want to handle registering the tokens and requesting permission yourself, you need to set config.autoCollectDeviceToken to NO. This prevents Swrve from swizzling the above methods. Note that it is necessary to include both of the following code snippets:

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
   SwrveConfig* config = [[SwrveConfig alloc] init];
   config.pushEnabled = YES;
   config.autoCollectDeviceToken = NO;
   [SwrveSDK sharedInstanceWithAppID:<app_id> apiKey:@"<api_key>" config:config launchOptions:launchOptions];
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
   if ([SwrveSDK messaging] != nil) {
      [[SwrveSDK messaging] setDeviceToken:deviceToken];

The push icon is blank on Android M

The Android SDK includes metadata configurations for remote notifications so they can be configured properly for Android L+.

For Android 6.0 you will need to also set the “SWRVE_PUSH_ICON_LARGE”. If you are using the latest version of our SDK (4.1+), you need to add the following three new pieces of metadata to the android manifest file:

<meta-data android:name="SWRVE_PUSH_ICON"
<meta-data android:name="SWRVE_PUSH_ICON_MATERIAL"
<meta-data android:name="SWRVE_PUSH_ICON_LARGE"
android:resource="@drawable/ic_launcher_large" />

Does the push look strange, or if no image is shown when expected

Be sure to follow the integration steps for rich push. On Android this is often caused by another push service consuming the push. As a test remove the other third party push service from your manifest and rebuild the app to see if this behaves the same way.

To ensure both services work correctly, follow the Swrve integration guide for Using Swrve push notifications with other providers.

On iOS, this may mean the notification service extension wasn't properly setup. Follow the steps in our iOS integration guide to ensure rich pushes appear correctly. For more information, see Creating a notification service extension.

The device can receive push notifications, but there are no engaged users

Are you sending the same push more than once during a session? Only the first one triggers a push engaged event, since Swrve doesn’t count engagement for duplicate pushes within a session. Try restarting the app in between tests.

Are you using the most recent Swrve SDK? We recommend upgrading when possible to the latest SDK release, to keep up to date with bug fixes and features. For iOS in particular, push handling is simplified from SDK 4.1. We update the SDK to keep up-to-date with platform changes.

It’s also possible that users have uninstalled the app.

Why is the push campaign targeting zero devices?

It can take a few hours after Swrve receives a push token for a device before Swrve can send live pushes to this user. This is because the push service takes the push token from the user databases, which are updated throughout the day. The QA user test pushes override this behavior and are available immediately.

Confirm that the audience filters are correct. User properties may not be being sent exactly as you expect, for example, targeting 'Platform = Apple' instead of 'Platform = iOS'.

The push was sent to less users than the campaign targeted

If the campaign details report shows that a number of users were targeted, but the push was sent to a smaller group of users, then the remaining users may have uninstalled the app.

Push engagement stats are too low

When a push campaign has been sent, you can view the Campaign Details page, which displays the following information:

  • How many devices were targeted for the push.
  • How many devices were not sent pushes due to the absence of a required user property, where no default value was specified.
  • How many push notifications were sent.
  • When the last push was sent.
  • How many push notifications failed to send.
  • How many batches failed.
  • How many push notifications Google or Android rejected immediately.

Apple and Google change how they deal with push tokens, so it is vital to keep up to date with the latest Swrve SDKs.


Google may reject push notifications for the following reasons:

  • Mismatch of Sender ID – Check the server key that has been uploaded on the Integrations Settings page, as it likely does not match the Sender ID/tokens being generated.
  • Invalid Token – The user may have uninstalled the app. Once you have uninstalled the app and reinstalled, you should hard-close the app and then reopen it to send the token to the dashboard. The device should now have a valid token, but it cannot be targeted for push notification campaigns until the next day.
  • Rejected or Deprecated Token. Google push will stop working with old tokens once a new version is uploaded to the play store. The push notifications plugin has been updated to the latest FCM library in Swrve SDK version 4.0.2 and above. This allows us to retrieve the correct token type returned from FCM. This leverages the new app instance ID for generating security tokens like for FCM. This updated API is required to handle token refreshes that happen.


Apple may reject a push notification for the following reasons:

  • Mismatch of push certificates – A development certificate only works for debug builds, so we typically suggest that you should upload a p12 file of the production APNS certificate to our dashboard. The issue may stem from a mismatch between the certificate on our dashboard and the APNS service.
  • For Apple information on troubleshooting push notifications, see their article on Troubleshooting Push Notifications.
  • Older versions of the SDK required two code paths to be implemented to handle the scenarios app completely closed and app in background. Make sure you have included both code sections, or upgrade to the latest SDK.

Push certificate renewal

Essentially the push certificate has to be updated every year in the Apple dev center. It doesn't require an app update.

To generate a new push certificate, visit This is typically managed by your iOS developers.

Once you have a new certificate, from the Settings menu, select Integration settings and upload the new certificate. (Note: You must have a Company Admin user role to upload the certificate). For more information, see How do I manage iOS push certificates for push notifications?

Note: Each app requires its own push certificate. The Apple push certificates are based on the bundle ID of the app - so each app needs to have its push certificate updated once a year.

Swrve will notify you 28 days before any certificate is due to expire, so you will always have some notice.

These alerts are automated for each app, and sent when an app's push certificate is due to expire in  28 days, 14, days, 7 days, 3 days, 1 day, and finally the day they expire. Alerts are sent to all Company Admins and to the assigned "Lead Developer" of the app in the Swrve.

Have more questions? Submit a request


Powered by Zendesk