Troubleshoot Your Push Implementation

Before proceeding to more specific troubleshooting, first review the basic MobilePush SDK troubleshooting information for Android and iOS implementations to identify any fundamental issues.

While troubleshooting, use the following questions as a checklist while testing and validating push notifications:

• Is the device registered in Marketing Cloud Engagement with a valid device token?
• Is the device opted-in to receive push notifications?
• Is the contact or device in the refreshed audience list or data extension that you set up and sent to in Engagement?
• Does Engagement show that the send job was completed?
• Did the device receive the notification?

If the answers to these questions are: Yes, Yes, Yes, Yes, and No, your implementation probably has an implementation issue related to receiving or displaying push messages on the device. Review the following sections for specific troubleshooting information.

If the answer to any of questions 1–4 is No, your implementation probably has an issue with registration or setting up your audience or ends correctly.

Contacts fail to receive push notifications for several reasons, including the following.

• The contact is associated with an invalid device token
• The contact is opted out for one of the following reasons
  • Invalid or malformed registrations
  • Feedback from the push notification service (Apple or Google)
  • Mismatched credentials (Sender ID, p12 Certificate, or p8 Auth Key)
  • Contact opted out on the device
• Contact wasn’t in the audience list for the push notification

The process of retrieving device tokens varies across platforms. For iOS, the app retrieves the device token and then forwards it to the SDK. For Android, the SDK typically manages the retrieval and registration of the device token automatically on behalf of the app. For more information, refer to steps 1–3 in the following diagram illustrating.

However, some Android implementations interfere with the device token retrieval process and require the app to forward the device token to the SDK, similar to iOS. In such cases, ensure that your app forwards an unmodified token to the SDK. Altering or custom handling of the device token risks creating a malformed, invalid, or delayed device token. In some cases, the app can fail to forward the device token to the SDK and Engagement entirely.

First, review the registration and the device token sent to Engagement by the SDK by following the steps to troubleshoot registrations. Also review the logs and the SDK state output.

To review the device token and other details stored in Engagement, follow these steps.

1. In Engagement, navigate to Audience Builder > Contact Builder > All Contacts > MobilePush channel.
2. Search for and select the contact key or device ID for the user that you’re troubleshooting.
3. On the contact’s Attributes tab, locate the MobilePush section.
4. Review the MobilePush channel details for the contact. Make sure that the device tokens (labeled System Token in the UI) appear to be well formed and the Status is active.

Make sure that the contact isn’t opted out due to invalid registration. Ensure that you’ve initialized and configured the SDK to register a valid device token and that the push_Enabled field is set to true (Android, iOS). If either of these values is missing from the registration payload, Engagement sets the contact as opted out.

Review the registration and the device token sent to Engagement by the SDK by following the steps to troubleshoot registrations. Also review the logs and the SDK state output.

To review opted out information, follow these steps.

1. In Engagement, navigate to Audience Builder > Contact Builder > All Contacts > MobilePush channel.
2. Search for and select the contact key or device ID for the user that you’re troubleshooting.
3. Click the Membership tab and navigate to the MobilePush section.
4. Review the contact's opt-out information.

Every time Engagement sends a push notification to the Push Notification Service (PNS), it receives feedback on whether the send succeeded or failed.

Some failure states are due to invalid or malformed tokens. The causes of this issue are noted under Review Invalid Device Tokens.

Other failure states are due to the fact that the contact’s device is opted-out of receiving push notifications. In this case, Engagement reacts to the PNS feedback and updates the contact’s record to be opted out, which is step 6c in the diagram.

To review the time and reason that a user was opted out, follow these steps:

1. In Engagement, navigate to Audience Builder > Contact Builder > All Contacts tab > MobilePush channel.
2. Search for and select the contact key or device ID for the user that you’re troubleshooting.
3. Click the Membership tab.
4. Review opt-out information.

Check whether your Android and iOS credentials, the server key, and .p8 authentication key that you uploaded in MobilePush Administration are correct. Sends fail if uploaded credentials are mismatched. To ensure that your credentials are correctly uploaded in MobilePush Administration, see Add Provisioning Info to Your App.

To send a message, Engagement requires a contact key. For MobilePush, Engagement uses the contact key to look up the corresponding device information for that audience, and then sends the message to their device or devices.

Before sending a test push notification, verify that the filtered list, filtered data extension, or standard data extension contains the correct contact keys for the recipients. To ensure that the contact keys are correct, refresh your audience before you send.

1. In Engagement, navigate to Mobile Studio > MobilePush > Overview tab.
2. Create a message.
3. On the Select Audience step, select the list.
4. Select Auto-refresh before send before clicking Next.
5. Finish creating your test message and send.

Depending on the automations set up within your account, added or modified audience records may not automatically be reflected in the filtered lists or filtered data extensions that you’re trying to send with. To ensure the contact key record is populated in the list or data extension you're testing with, refresh the filtered list or filtered data extension. Standard data extensions don’t require a refresh.

Ensure that you correctly configure any overrides or customizations to push notification handling, such as supporting rich image notifications or saving notifications locally in the app or inbox. Review information about customized notifications in the platform-specific push notification guides for Android and iOS.

Silent push notifications are notifications that your app receives in the background. They’re designed for processing without displaying on the device. To enable your app to handle silent push notifications, use the SilentPushListener method in Android. For iOS, see Silent Push Notifications.

After a contact opens a notification on the device, the SDK records the analytic event. The SDK submits analytics to Engagement after the application goes into the background or comes into the foreground. If a user forces the app to close, the analytic event is stored and submitted to Engagement after the next app open. It can take up to five minutes for Engagement servers to process and make the analytics available.

The three most common reasons for why engagement analytics don’t show up in Engagement are tied to initialization of the SDK.

• Failed or delayed initialization can lead to delayed, duplicate, or missing analytics data. Ensure that the MobilePush SDK is successful in initializing.
• The SDK records and submits analytic events only if etanalytics is configured. As part of initialization, ensure that the builder is configured with etanalytics enabled.
• Android requires a callback for analytics.

If you use more than one push SDK in your app, review multiple push providers documentation (Android, iOS).