This troubleshooting guide will walk through common iOS issues. Before you begin
verify the SDK is setup properly by following iOS SDK Setup Guide,
double check app credentials in the airship config match the credentials in the dashboard, and
automaticSetupEnabled is disabled, verify all the proper methods are being
forwarded to the
Urban Airship SDK.
Remote notifications are not supported on a simulator. Make sure you are testing on a real device.
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
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 iOS Platform Guide.
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 and handling notifications 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 (
maintains the connection to Apple’s servers. If this daemon loses its
connection, it will reconnect… eventually. Depending on network
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
In-app messaging requires content-available push notification. All troubleshooting steps above should also be considered for 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.
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).
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.
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.
If you are experiencing throttling, only the in-app portion of a message will experience the effects. That is, if you send a combination push notification and in-app message, the push notification will still be delivered, even if the in-app message is dropped.
App is neither backgrounded nor open
In-app message display issues may occur if the app has been force quit shortly before receiving an in-app message. To avoid this issue, refrain from force quitting an app before sending it an in-app message.
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.
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:
- Apple tells us that the application has been uninstalled via the feedback service, which we check on a regular basis.
- 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.
- We receive an explicit delete call on the device token, which marks it as inactive and clears the alias and any associated tags.
- If the device token was created when iOS 6 was installed, and the device has since updated to iOS 7, the old device token is eventually rejected by Apple because the device now has a new, app-specific iOS 7 device token. To check your current device token, please see this support article.
In any case, applications should expect and handle inactive device tokens properly. We recommend that developers do one of the following:
- Register the device token every time the application is opened, like our sample app does
- Use our feedback API regularly, store inactivated device tokens in your own database, and send registrations when the device token becomes active again.
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
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 Urban 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
codesigntool to verify your build’s entitlement (look for
codesign -dvvv --entitlements - <YourAppName>.app)
Other registration issues
Apple’s Troubleshooting Push Notifications technical
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 Urban Airship Engage Knowledge Base for additional assistance.