This troubleshooting guide will walk through common iOS issues. Before you begin verify the SDK is set up properly by following iOS SDK Setup Guide, double check app credentials in the airship config match the credentials in the dashboard, and if automaticSetupEnabled is disabled, verify all the proper methods are being forwarded to the Airship SDK.

Missing notifications

Simulator

Remote notifications are not supported on a simulator. Make sure you are testing on a real device.

Check capabilities

Verify in your target’s capabilities that remote-notifications background mode is enabled and push notifications are turned on.

User notifications enabled?

Before remote-notifications are able to post any content to the user’s notifications center, it must first prompt the user for permission to do so. This is controlled by the userPushNotificationsEnabled flag on the UAPush instance. Once enabled and permissions are accepted, the application is then able to display user notifications.

For more details on enabling notifications, see Getting Started with Push Notifications.

Foreground notifications

When a notification is received in the foreground it is up to the application to notify the user. APNs by default will not show the notification. The easiest way to verify a notification being received is to simply background the application before sending the notification. Once you verified everything is being sent, you can then update the application to handle notifications in the foreground. See foreground presentation options for more information.

Cellular data connectivity

Under ideal circumstances, APNs will maintain a persistent connection to each device. This strategy saves power by avoiding polling, allowing the radio interface more time to sleep. On the device, a daemon (apsd) maintains the connection to Apple’s servers. If this daemon loses its connection, it will reconnect… eventually. Depending on network conditions, apsd can take a while to retry and reestablish connectivity. If several notifications were sent while the device was off-line, only the latest one would be delivered.

Networks may restrict access to tcp/5223

iOS devices connect to the APNs service on TCP port 5223. If the local (client-side) network restricts access to this port, push notification delivery will fail.This problem is most commonly observed on WiFi provided by employers with restrictive default-deny outbound firewall policies.

WiFi is being used for push notifications

Given the choice between WiFi and cellular, APNs will prefer to use cellular and maintain a persistent connection to the device. However, if cellular is not available, a slightly different strategy is used. Some older devices with WiFi only will switch to polling the Apple Push Notification service every 15 minutes when the display turns off and the device sleeps to conserve power. (i.e., A persistent connection is not maintained.) Keeping the device on USB power will maintain the connection.

Missing in-app messages

Under certain circumstances, in-app messages will not be received by devices. This behavior will rarely be present in a production scenario, but it can occur during demoing or testing in-app messages. We list several possible causes for this behavior, along with strategies for avoiding display issues.

Check AirshipAutomation integration

In-app messaging requires the AirshipAutomation module. In CocoaPods this must be integrated by adding either the umbrella Airship pod or Airship/Automation pod to your Podfile.

Similarly in SPM you must add either the umbrella Airship library or the AirshipAutomation library.

Otherwise when integrating manually you must directly add the AirshipAutomation framework to your project.

For more integration details see:

• CocoaPods configuration
• SPM configuration
• Manual configuration

Killing the application

Killing the application (swipe up from task list) prevents the application from being launched when a background notification is received. If the notification contains an alert, the alert will still be shown. Notifications that are “silent” are ignored.

Content-available pushes will trigger an application’s notification delegate callbacks again if launched from the alert itself. If you need to test for cases where the application is in a “not-running” state, run and stop the application from Xcode or restart the device.

Background time is not guaranteed

Apple reserves the right to not wake up your application when a background notification is received in order to maximize the devices battery life. This usually happens if you send too many content-available pushes in a short period of time.

The notification will still be displayed if it contains either an alert, badge, or sound.

Permissions during background push callbacks

When a background push is received the device may not be in a state where your application has full permissions (such as a PIN locked device).

You should take limited permissions into consideration when defining your application’s behavior during background push handling (e.g., keychain access).

Cellular data

Issues with in-app message display are more present when the device is using cellular data. For this reason, when testing or demoing in-app messages, we recommend disabling cellular data and using WiFi exclusively.

Throttling

Apple may choose to throttle your message sending, especially if you send large numbers of messages close together. If cellular data cannot be avoided, you should not send more than 4-5 in-app messages in an hour.

As long you are sending reasonable numbers of in-app messages, you should not see these issues in production. If you are seeing these issues in production, throttling is most likely the root cause, in which case you should reevaluate your push strategy and consider sending fewer in-app messages.

APNs registration

Inactive device token

There are times during development or perhaps you’ve launched your app to the app store and you see either your token or messages of inactive tokens in your UA application. We mark a device token as inactive when one of four things happen:

1. Apple tells us that the application has been uninstalled via the feedback service, which we check on a regular basis.
2. Apple rejected the device token for your app upon receipt of the notification at their servers. You can find more information about what causes this in this support article .
3. We receive an explicit delete call on the device token, which marks it as inactive and clears the alias and any associated tags.

In any case, applications should expect and handle inactive device tokens properly. We recommend that developers register the device token every time the application is opened, like our sample app does.

Rejected device token

When Apple rejects a device token, it means that for the particular push environment (sandbox or production), the device token is not recognized.

Device tokens are generated by the Apple Push Notification service when your application requests remote notifications by registering through iOS.

Device tokens serve the purpose of a unique identifier, but they are cryptographically generated by APNs, and returned to the device. This token, combined with your application’s aps-environment entitlement, is what allows for push notifications to be sent through APNs to your users.

In turn, when an application registers for push notifications using our SDK, it uses the registration API to associate that device token with your app configuration at Airship.

Troubleshooting rejected device tokens:

• Don’t use a production app key in your application unless it is a distribution build (e.g., ad hoc or App Store)
• Ensure that ad hoc builds are using production app keys.
• Verify that device tokens aren’t appearing in both your development app configuration and production app configuration. This shouldn’t happen, and indicates a production/development mismatch.
• Use the codesign tool to verify your build’s entitlement (look for aps-environment : codesign -dvvv --entitlements - <YourAppName>.app)

Other registration issues

Apple’s Troubleshooting Push Notifications technical note  has a debugging profile that enables verbose debugging for the apsd push daemon. With this you can observe all communication with the push service, including what apps are listening and arriving push notifications. The configuration profile can be downloaded by clicking Companion File at the upper right corner of that page.

iOS Knowledge Base

Please visit the Airship Knowledge Base for additional assistance.

• iOS Knowledge Base Forum 
• iOS Knowledge Base Articles 
• Rejected Device Token Troubleshooting