Troubleshooting Mobile Push Notifications in SAS® Customer Intelligence 360
For various reasons, push notifications or in-app messages to customers and their devices can fail to reach the targeted device. This article provides some steps that you can complete to troubleshoot this issue.
Enable Push Notifications or In-App Messages
In order to send push notifications or in-app messages, you must implement the SAS Customer Intelligence 360 Mobile Software Development Kit (SDK). For more information, see SAS® Customer Intelligence 360: Developer’s Guide for Mobile Applications.
In addition, the SAS Customer Intelligence 360 Mobile SDK section also provides tutorial videos on how to implement and initialize the SDK for both iOS and Android, such as the following:
- iOS: Installing the iOS Mobile SDK | Customer Intelligence 360
- Android: Installing the Android Mobile SDK | Customer Intelligence 360
Once you install the SDK, you must enable mobile messages for the SDK or application through your device as follows:
After you enable mobile messages, make sure that you satisfy all of the prerequisites, which are described in the Prerequisites for Receiving a Mobile Push Notification section. Note that it is good practice to set up a test (or debug) version of the application that you are developing. Make sure that you install this application on testing devices so that you can simulate the real-world use cases in production. This practice helps you ensure that the use cases function as intended.
Eliminating any possible prerequisites as the root cause of this problem is a good way to narrow down the scope of possible issues. Using a testing device before you implement the application into production also enables you to understand how the use case should be working and capture any potential flaws or issues related to the application code or SDK implementation.
If you are able to fulfill the prerequisites but still do not observe the exact root cause of why the push notification did not reach the targeted device, see the Troubleshoot the Delivery of Mobile Push Notifications section.
Diagnostics
The Diagnostics tool is a great way to look up and find details associated with an identity and its associated devices. You can use the tool to verify associations between the identity and registered devices, associations to the application ID, and to test and verify the reachability of the devices associated with the identity.
Note: The Diagnostics tool is useful for verifying the implementation of the mobile messaging parts of the SDK without adding complexity and potential issues related to mobile push notification tasks. SAS suggests that you use the Diagnostics tool first to confirm that the mobile messages reach the device before proceeding to set up and use the mobile push notification tasks.
You can use this tool to initially test reachability from SAS Customer Intelligence 360 to potential test devices and development applications before you proceed in setting up use cases, creating tasks, and sending push notifications to real customer devices. For example, the following identity contains two associated devices, which indicates that this single user accessed the application with the SDK using two different devices:
On the Identity Profile tab, you can determine whether the device is reachable by selecting the device and then sending a test push notification to the device, as shown in the following image:
You also have the option of manually detaching the device from the identity if you do not want the identity to be associated to this device anymore.
Job Information Monitor
The Job Information monitor tool is located inside the Tasks workspace and provides a list of executions for published emails, including mobile push notifications. (For more information, see the Monitor the Execution of Bulk Push Notification Tasks section). The Job Information monitor tool displays the status per execution attempt, the progress, total recipients targeted and processed and completed, and total recipients failed and skipped (including the possible reason why they failed or were skipped).
To use the tool, in the Tasks workspace, click the Job Information button in the top right corner. Then, click a specific execution related to a mobile Push Notification, as shown in the following image:
Clicking the i button below the Recipients Failed column displays more details:
In addition, clicking the i button below the Recipients Skipped column displays more details:
These additional details are useful for each of the issues above that can occur. For example, if you want to understand why 36.330 devices were skipped, you can access the “Metrics for Mobile Push Notification Send Failures” sub-section under Monitor the Execution of Bulk Push Notification Tasks for more details about each potential issues.
In this scenario, the token needs to be properly generated and attached to the device before a mobile push notification can be sent to the device. As a result, you might need to review how the mobile application code and the SDK registers the mobile push token for the device.
UDM tables
SAS Customer Intelligence 360 collects data per mobile push notification execution in the following UDM tables:
The NOTIFICATION_SEND table captures data about push notifications that were successfully sent to devices. The NOTIFICATION_OPENED table captures data about push notifications being opened on the targeted device. The NOTIFICATION_FAILED table, however, captures data about push notifications that somehow failed to be sent or failed to reach the targeted device.
The NOTIFICATION_FAILED table contains the error_message_txt column, which contains information about why the push notification execution did not reach the targeted device. The NOTIFICATION_FAILED table also contains the error_cd column, which contains error codes served from APNS or FCM. The error_message_txt column in the NOTIFICATION_FAILED table might also include some of the following error messages:
Platform token associated with the endpoint is not valid
This error is typically associated with the APNS certificate or key related to the mobile application definition or changes made to the device token.
If the error is associated with the device token, it is possible that the token was changed but not yet updated in the application code itself. You should update the mobile token with the back-end on every focus.
Here are some other possible causes for this error:
- The app was uninstalled, or the token was otherwise revoked (for example, by clearing the local data).
- The app is a development install from Xcode, so the token and the credentials registered with SAS Customer Intelligence 360 are mismatched.
- The application could have been built using the incorrect certificate. You might build an application that uses the DEVELOPMENT certificate instead of the PRODUCTION certificate. As a result, the back-end was set up with one certificate, and there is no way to know whether the token is DEVELOPMENT or PRODUCTION until after you attempt the push notifications.
The device endpoint is disabled
AWS disables the device endpoint when SAS Customer Intelligence 360 tries to send push notifications to the device. This error might occur when the push notification is sent to the same device and the notification fails multiple times (or for some other reason is stopped by AWS).
Device Endpoint Is Invalid
An AWS response typically points toward the device endpoint no longer existing. This error usually means that the parent application was removed from the device, or the application definition in SAS Customer Intelligence 360 was deleted and recreated.
In addition, the error can be related to the NotificationChannel not being initialized or declared properly in the application code. You should ask the developer to check the Enable Mobile Messages for Android Devices or Enable Mobile Messages for iOS Devices documentation and confirm that the NotificationChannel was initialized or declared properly in the application code.
Device Token Not Registered by the Mobile App
The mobile app code has bound the mobile device to an identity in the target audience but failed to register a mobile push token.
This error is typically related to the token registration for the device. For internal test devices, you should do the following:
- Log out of the application.
- Turn on the DEVICE logs or SDK logging.
- Log back on and retry the push notification or in-app message.
The log should explain if the token was properly created or updated for the device, which needs to work in order for that device to receive push notifications.
In addition, this error can occur if the NotificationChannel is not set properly. You should check the Enable Mobile Messages for Android Devices or Enable Mobile Messages for iOS Devices documentation for more information.
Note that the error_cd column also contains error codes related to the reason provided in the error_message_txt column. These error codes are sent from the AWS SNS intermediary service.
SDK Logging (or Device Logging)
The SAS Customer Intelligence 360 SDK provides a default logger class for both Android and iOS versions of the SDK that can be enabled and modified.
- iOS: Enable SDK Internal Logging
- Android: Enable SDK Internal Logging
You can enable and use the SDK Internal Logging class to collect information about how the device, application, and the SDK behaves during certain situations, which is useful during development and testing periods. The SDK Internal Logging class can also be useful in cases where mobile push notifications do not reach internal devices.
You might choose to create a debug version of the mobile application (with additional SDK logging enabled) for internal testing before you proceed to create and publish the production version of the application. When you create a debug version, you can test different use cases that involve various activities (such as triggering and receiving push notifications). The additional SDK logging is useful for troubleshooting potential issues.
You typically need to enable the SDK logging when a specific issue occurs within an application using the SDK and where the same problem can be replicated by an internal testing device. You can enable the SDK logging for that specific device, make the device replicate the issue, and then review the logs produced by the SDK logging to troubleshoot the cause of the potential problem.
You can enable the SDK logging by embedding the SASLogger class to your application code. See the following videos for instructions about implementing and initializing the SDK for iOS and Android. (The videos also contain details about adding and initializing the SASLogger class.)
General Recommendations
Here are some general tips that you should complete to successfully use mobile push notifications:
- iOS: Use a command line to send test push notifications, which quickly helps test the setup with APNS in a non-production test application. See Sending push notifications using command-line tools for additional information.
- See the "Troubleshooting Bulk Push Notifications" sub-section in Troubleshoot Mobile Push Notifications for other potential problems that you can encounter when sending mobile push notifications.
- Generally, always refresh the device token on every focus event in the application with the back-end. A focus event occurs when a user opens or closes a mobile application or page in application. Following this best practice ensures that the mobile token associated with the device and application is kept updated.
- Keep the SAS Customer Intelligence 360 mobile SDK updated with the latest updates, fixes, and functions.
- To ease the troubleshooting process related to mobile push notifications, ensure that you have one or more test devices (using both iOS and Android) where you can attempt to replicate the behavior.
- Generally, create two mobile application definitions in SAS Customer Intelligence 360. Create one definition for production (using production certificates) and one for development (using sandbox or test certificates). Note that both definitions should use separate certificates.
