Skip to main content

iOS Troubleshooting

Problems specific to the iOS SDK. Start with the platform independent checks in Troubleshooting, especially when events are missing in the panel.

Diagnostic steps​

  1. Check the SDK version in your Package.resolved or Podfile.lock. Many problems below are fixed in 1.2.0 or 1.3.0.
  2. Print UserSDK.default?.userKey after the first ping. If it is nil, the SDK has no contact yet and does not send events.
  3. Read the completion handlers of ping, sendEvent and trackScreen, or set UserSDK.errorHandler, and log the errors. See Errors.
  4. Find the contact with this key in the panel and compare it with the contact you were looking at.
  5. For push notifications and in-app messages, test on a physical device and check that UIBackgroundModes with remote-notification is in the built app's Info.plist.

Problems​

Events fail with notIdentified​

Symptom: the completion of sendEvent, trackScreen or sendProductEvent reports false at once, with UserSDKError.notIdentified and the message "No user exists yet". The SDK sends no request, so a network proxy shows no event traffic at all.

Causes:

  • the event was sent before the first successful ping() of this installation,
  • ping() is never called, or it fails (wrong key, wrong domain, no network on first launch).

Fix:

  1. Call ping() after initialization on every launch.
  2. Check its completion. A 401 means the Mobile SDK key is wrong, regenerated, or is the REST API key. See Nothing reaches the panel.
  3. Send events after the ping succeeds, for example from its completion on the first launch.

The contact cannot be selected in a push campaign​

Symptom: the contact exists in the panel, but a push or in-app campaign does not let you choose it.

The panel offers only contacts with a device that has a push token. A contact without one cannot be targeted at all.

Causes:

  • no FCM token passed to the SDK,
  • the token moved to another contact on the same device: a push token belongs to the device, and a ping with it moves the device to the contact that sent the ping, for example after another user logged in on that device or after logout,
  • SDK 1.2.x or earlier: an app woken in the background on a locked phone created a duplicate anonymous contact and moved the token to it.

Fix:

  1. Check that setFcmToken(_:) (or another method with fcmToken) runs with a non empty token. See Firebase and FCM Token.
  2. Open the app, so the next ping registers the current token on the current contact.
  3. On 1.2.x or earlier, update to 1.3.0.

Push notifications do not arrive​

Symptom: the campaign is sent to the contact, but the push notification never appears on the device.

Causes:

  • no APNs key in the Firebase project, or the Push Notifications capability is missing,
  • the panel uses a service account key from a different Firebase project,
  • notifications are turned off for the app in the iOS Settings app.

Fix:

  1. Check the APNs key in Firebase Console → Project settings → Cloud Messaging.
  2. Compare the Firebase project in GoogleService-Info.plist with the one in the panel.
  3. Check the permission in the iOS Settings app.

In-app messages do not appear​

Symptom: push notifications work, but in-app messages never show up.

Causes:

  • application(_:didReceiveRemoteNotification:fetchCompletionHandler:) is missing, does not call handleNotification(_:), or is in a class iOS does not use as the app delegate,
  • the Remote notifications background mode is missing from the built Info.plist,
  • the message was sent while the app was closed (swiped away), or more than 6 hours before the app was opened,
  • the SDK version is earlier than 1.2.0 and the app forwards notifications from a background queue or a Task.

Fix:

  1. Add the method to the real app delegate. In SwiftUI, to the class attached with UIApplicationDelegateAdaptor.
  2. Enable Background Modes → Remote notifications.
  3. With Firebase method swizzling turned off, also call Messaging.messaging().appDidReceiveMessage(_:) there, as Firebase requires.
  4. Test with the app open first, then in the background.
  5. Update to 1.2.0.

In-app messages do not need notification permission, as long as your app registers with APNs and passes the FCM token. If your app calls registerForRemoteNotifications() only after the user allows notifications, users who decline get no in-app messages.

Push notification clicks are not counted​

Symptom: users tap push notifications, but the panel shows no clicks.

Causes:

  • your UNUserNotificationCenterDelegate does not forward taps to the SDK,
  • another library replaced your notification center delegate,
  • your app passes taps to handleNotification(_:), which never counts a click.

Fix:

  1. Call handleNotificationClick(_:) in userNotificationCenter(_:didReceive:withCompletionHandler:).
  2. Check which object is UNUserNotificationCenter.current().delegate after launch.

Push notifications are counted as clicked without a tap​

Symptom: the panel shows clicks for push notifications nobody tapped, often close to the number of deliveries. It also happens for users who did not grant notification permission.

Cause: your app calls the deprecated handleNotification(userInfo:) from userNotificationCenter(_:willPresent:withCompletionHandler:) or from application(_:didReceiveRemoteNotification:fetchCompletionHandler:). iOS calls these methods for notifications that were only received, willPresent even without notification permission, and the deprecated method counts every call as a click.

Fix: update to 1.3.0 and switch to the new methods:

  1. Call handleNotificationClick(_:) in userNotificationCenter(_:didReceive:withCompletionHandler:).
  2. Call handleNotification(_:) in application(_:didReceiveRemoteNotification:fetchCompletionHandler:), and in willPresent if you like. It never counts a click. In-app messages arrive through didReceiveRemoteNotification, so they keep working.

On 1.2.x, remove the handleNotification(userInfo:) call from willPresent.

Push notifications and in-app messages go to an anonymous contact​

Symptom: on versions earlier than 1.3.0, a logged in user stops getting push notifications or in-app messages. The panel shows anonymous contacts with the same device model, created around the time a campaign was sent.

Cause: a silent push woke the app in the background on a locked phone, and the SDK could not read the contact key. The ping sent then created a new anonymous contact and moved the push token to it.

Fix: update to 1.3.0. See Duplicate anonymous contacts from one iOS device.

Your own foreground notifications stopped showing a banner​

Symptom: on versions earlier than 1.3.0, after adding the SDK, notifications in the foreground play a sound but show no banner.

Cause: registerForRemoteNotifications(options:notificationDelegate:) made the SDK the notification center delegate, and before 1.3.0 it presented foreground notifications with badge and sound only. From 1.3.0 it shows them as banners.

Fix: update to 1.3.0, or keep your own delegate and forward notifications to the SDK instead. See Push Notifications, Option A.

Push notification image is not shown​

Symptom: the notification arrives without its image.

Causes:

  • no Notification Service Extension, or it does not call NotificationExtensionHelper,
  • the image URL is not HTTPS, is not public, or the file is larger than iOS accepts,
  • the image server answers too slowly.

Fix:

  1. Add the extension as described in Show images.
  2. Use a public HTTPS URL to a small image file.

'UserSDK' is unavailable in application extensions​

Symptom: a compile error in a Notification Service Extension or another extension target.

Cause: UserSDK cannot run in app extensions.

Fix: in the extension use only NotificationExtensionHelper.

Contact data from another workspace or environment​

Symptom: after switching baseURL (for example from staging to production), events go to an unknown contact or are rejected.

Cause: the contact key is stored in the Keychain and kept when baseURL changes. The SDK resets it only after the app is deleted and installed again.

Fix: delete the app from the device before testing with another workspace, or call logout(fcmToken:_:) once after switching.

Events sent right after logout fail​

Symptom: on versions earlier than 1.2.0, sendEvent and trackScreen report "No user exists yet" after logout, until the next ping.

Fix: update to 1.2.0. Events sent after logout completes no longer fail with "No user exists yet". While logout is in progress, until its completion handler runs, there is no contact key and events still report this error.

Contact support​

If the problem persists, contact Positive User support through the chat widget in your workspace or on user.com, or your Customer Success Manager. Include the SDK version, iOS version and device model, the contact key from UserSDK.default?.userKey, the time of the test, the completion errors, and your notification setup (own delegate or registerForRemoteNotifications, Firebase swizzling on or off).