AppboyKit (also known as the Objective-C SDK) is no longer supported and has been replaced by the Swift SDK. It will no longer receive new features, bug fixes, security updates, or technical support—however, messaging and analytics will continue to function as normal. To learn more, see Introducing the New Braze Swift SDK.
Troubleshooting
Understanding the Braze/APNs workflow
The Apple Push Notification service (APNs) is Apple’s infrastructure for push notifications sending to iOS and OS X applications. Here is the simplified structure of how push notifications are enabled for your users’ devices and how Braze can send push notifications to them:
- You configure the push certificate and provisioning profile
- Devices register for APNs and provide Braze with push tokens
- You launch a Braze push campaign
- Braze removes invalid tokens
Step 1: Configuring the push certificate and provisioning profile
In developing your app, you’ll need to create an SSL certificate to enable push notifications. This certificate will be included in the provisioning profile your app is built with and will also need to be uploaded to the Braze dashboard. The certificate allows Braze to tell APNs that we are allowed to send push notifications on your behalf.
There are two types of provisioning profiles and certificates: development and distribution. We recommend just using distribution profiles and certificates to avoid any confusion. If you choose to use different profiles and certificates for development and distribution, ensure that the certificate uploaded to the dashboard matches the provisioning profile you are currently using.
Do not change the push certificate environment (development versus production). Changing the push certificate to the wrong environment can lead to your users having their push token accidentally removed, making them unreachable by push.
Step 2: Devices register for APNs and provide Braze with push tokens
When users open your app, they will be prompted to accept push notifications. If they accept this prompt, APNs will generate a push token for that particular device. The iOS SDK will immediately and asynchronously send up the push token for apps using the default automatic flush policy. After we have a push token associated with a user, they will show as “Push Registered” in the dashboard on their user profile under the Engagement tab and will be eligible to receive push notifications from Braze campaigns.
As of Xcode 14, you can test remote push notifications on an iOS simulator.
Step 3: Launching a Braze push campaign
When a push campaign is launched, Braze will make requests to APNs to deliver your message. Braze will use the SSL push certificate uploaded in the dashboard to authenticate and verify that we are allowed to send push notifications to the push tokens provided. If a device is online, the notification should be received shortly after the campaign has been sent. Note that Braze sets the default APNs expiration date for notifications to 30 days.
Step 4: Removing invalid tokens
If APNs informs us that any of the push tokens we were attempting to send a message to are invalid, we remove those tokens from the user profiles they were associated with.
Utilizing the push error logs
Braze provides a log of push notification errors within the Message Activity Log. This error log provides a variety of warnings which can be very helpful for identifying why your campaigns aren’t working as expected. Clicking on an error message will redirect you to relevant documentation to help you troubleshoot a particular incident.
Common errors you might see here include user-specific notifications, such as “Received Unregistered Sending to Push Token”.
In addition, Braze also provides a push changelog on the user profile under the Engagement tab. This changelog provides insight into push registration behavior such as token invalidation, push registration errors, tokens being moved to new users, etc.
Push registration issues
To add verification for your application’s push registration logic, implement push unit testing.
No push registration prompt
If the application does not prompt you to register for push notifications, there is likely an issue with your push registration integration. Ensure you have followed our documentation and correctly integrated our push registration. You can also set breakpoints in your code to ensure the push registration code is running.
No “push registered” users showing in the dashboard
- Check that your app is prompting you to allow push notifications. Typically, this prompt will appear upon your first open of the app, but it can be programmed to appear elsewhere. If it does not appear where it should be, the problem is likely with the basic configuration of your app’s push capabilities.
- Verify the steps for push integration were successfully completed.
- Check that the provisioning profile your app was built with includes permissions for push. Make sure that you’re pulling down all of the available provisioning profiles from your Apple developer account. To confirm this, perform the following steps:
- In Xcode, navigate to Preferences > Accounts (Or use the keyboard shortcut Command+,).
- Select the Apple ID you use for your developer account and click View Details.
- On the next page, click Refresh and confirm that you’re pulling all available provisioning profiles.
- Check you have properly enabled push capability in your app.
- Check your push provisioning profile matches the environment you’re testing in. Universal certificates may be configured in the Braze dashboard to send to either the development or production APNs environment. Using a development certificate for a production app or a production certificate for a development app will not work.
- Check that you are calling our
registerPushToken
method by setting a breakpoint in your code. - Check that you are on a device (push will not work on a simulator) and have good network connectivity.
Devices not receiving push notifications
Users no longer “push registered” after sending a push notification
This likely indicates that the user had an invalid push token. This can happen for several reasons:
Dashboard and app certificate mismatch
If the push certificate you uploaded in the dashboard is not the same one in the provisioning profile that your app was built with, APNs will reject the token. Verify that you have uploaded the correct certificate and completed another session in the app before attempting another test notification.
Uninstalls
If a user has uninstalled your application, their push token will be invalid and removed upon the next send.
Regenerating your provisioning profile
As a last resort, starting over fresh and creating a whole new provisioning profile can clear up configuration errors that come from working with multiple environments, profiles, and apps at the same time. There are many “moving parts” in setting up push notifications for iOS apps, so sometimes, it is best to retry from the beginning. This will also help isolate the problem if you need to continue troubleshooting.
Users still “push registered” after sending a push notification
App is foregrounded
On iOS versions that do not integrate push via the UserNotifications
framework, if the app is in the foreground when the push message is received, it will not be displayed. You should background the app on your test devices before sending test messages.
Test notification scheduled incorrectly
Check the schedule you set for your test message. If it is set to local time zone delivery or Intelligent Timing, you may have just not received the message yet (or had the app in the foreground when it was received).
User not “push registered” for the app being tested
Check the user profile of the user you are trying to send a test message to. Under the Engagement tab, there should be a list of “pushable apps”. Verify the app you are trying to send test messages to is in this list. Users will show up as “Push Registered” if they have a push token for any app in your workspace, so this could be something of a false positive.
The following would indicate a problem with push registration or that the user’s token had been returned to Braze as invalid by APNs after being pushed:
Message activity log errors
Received unregistered sending to push token
- Make sure that the push token being sent to Braze from the method
[[Appboy sharedInstance] registerPushToken:]
is valid. You can look in the Message Activity Log to see the push token. It should look something like6e407a9be8d07f0cdeb9e724733a89445f57a89ec890d63867c482a483506fa6
, a long string containing a mix of letters and numbers. If your push token looks different, check your code for sending Braze the push tokens. - Ensure that your push provisioning profile matches the environment you’re testing. Universal certificates may be configured in the Braze dashboard to send to either the development or production APNs environment. Using a development certificate for a production app or a production certificate for a development app will not work.
- Check that the push token you have uploaded to Braze matches the provisioning profile you used to build the app you sent the push token from.
Device token not for topic
This error indicates that your app’s push certificate and bundle ID are mismatched. Check that the push certificate you uploaded to Braze matches the provisioning profile used to build the app from which the push token was sent.
BadDeviceToken sending to push token
The BadDeviceToken
is an APNs error code and does not originate from Braze. There could be a number of reasons for this response being returned, including the following:
- The app received a push token that was invalid for the credentials uploaded to the dashboard.
- Push was disabled for this workspace.
- The user has opted out of push.
- The app was uninstalled.
- Apple refreshed the push token, which invalidated the old token.
- The app was built for a production environment, but the push credentials uploaded to Braze are set for a development environment (or the other way around).
Issues after push delivery
To add verification for your application’s push handling, implement push unit tests .
Push clicks not logged
- If this is only occurring on iOS 10, make sure you have followed the push integration steps for iOS 10.
- Braze does not handle push notifications received silently in the foreground (for example, default foreground push behavior prior to the
UserNotifications
framework). This means that links will not be opened, and push clicks will not be logged. If your application has not yet integrated theUserNotifications
framework, Braze will not handle push notifications when the application state isUIApplicationStateActive
. You should ensure that your app does not delay calls to our push handling methods; otherwise, the iOS SDK may treat push notifications as silent foreground push events and not handing them.
Web links from push clicks not opening
iOS 9+ requires links to be ATS compliant to be opened in web views. Ensure that your web links use HTTPS. Refer to our ATS compliance article for more information.
Deep links from push clicks not opening
Most of the code that handles deep links also handles push opens. First, ensure that push opens are being logged. If not, fix that issue (as the fix often fixes link handling).
If opens are being logged, check whether it is an issue with the deep link in general or with the deep linking push click handling. To do this, test to see if a deep link from an in-app message click works.
Few or no direct opens
If at least one user opens your iOS push notification, but few or no Direct Opens are logged to Braze, there may be an issue with your SDK integration. Keep in mind, Direct Opens are not logged for test sends or silent push notifications.
- Make sure that the messages are not being sent as silent push notifications. The message must have text in the title or body to not be considered silent.
- Double-check the following steps from the push integration guide:
- Register for push: On every single app launch, preferably within
application:didFinishLaunchingWithOptions:
, the code from step 3 needs to occur. The delegate property ofUNUserNotificationCenter.current()
needs to be assigned to an object that implementsUNUserNotificationCenterDelegate
and contains the(void)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:
method. - Enable push handling: Verify that the
(void)userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:
method has been implemented.
- Register for push: On every single app launch, preferably within