How do I troubleshoot FCM mobile push notification failures in Amazon SNS?

Resolution

Configure and view push notification delivery status attributes for Amazon CloudWatch Logs

Follow the instructions in How do I access Amazon SNS topic delivery logs for push notifications?

Confirm that the device can connect to push notification servers

If the issue is occurring only on a specific device, then make sure that the device can connect to push notification servers. For example, your firewall might restrict traffic that allows mobile devices to connect with FCM on your network. For more information, see FCM ports and your firewall on the Firebase website.

Check if the device's associated platform endpoint is activated

Check the failed push notification delivery logs for the "providerResponse": "Endpoint is disabled" value.

Example:

{  "notification": {
    "messageMD5Sum": "c8c339cf07dc39c9388253dgc81f257",
    "messageId": "fg207f98-0244-6767-96e2-45b1fg451gg8",
    "timestamp": "2023-06-23 16:27:51.889"
  },
  "delivery": {
    "deliveryId": "76ab7dcd-f444-5b4f-9d1b-24ea8863d9bc",
    "destination": "arn:aws:sns:us-east-1:123456789101:endpoint/GCM/MyAndroidApp/682dc992-a47f-45f7-b980-97727cce0a9c",
    "providerResponse": "Endpoint is disabled",
    "dwellTimeMs": 28,
    "attempts": 1,
    "token": "ojnco9nc9weucn9encx9ewunc9nu9w9euncec9necn9xexnexex9encewcerve0f0o0dmco9j",
    "statusCode": 400
  },
  "status": "FAILURE"
}

If you see the "providerResponse": "Endpoint is disabled" value in the failed delivery logs, then the device's associated platform endpoint is deactivated. To troubleshoot this issue, see Why is my push notification endpoint not active?

For more information, see Reinitiating a platform endpoint associated with an invalid device token.

Verify that you can receive notifications directly from FCM

To determine if the issue is on the Amazon SNS endpoint side or the client application side, send a test message on the FCM console. For instructions, see Send a test notification message on the Firebase website.

Confirm that you're using the correct FCM message type

FCM supports notification messages and data messages. The FCM SDK automatically handles notification messages. The client app handles data messages. For more information, see Message types on the Firebase website. Also, see Sending platform-specific messages.

Set the data key to process message data on your client app

Make sure that you set the data key with your custom key-value pairs to send a data payload to the client app. For more information, see Data messages on the Firebase website.

Use the FCM SDK to display notifications for your client app

Make sure that you use the notification key with the predefined set of key-value options for the notification message. For more information, see Notification messages on the Firebase website.

Identify and troubleshoot push notification error response codes

Complete the following steps:

1. Review your delivery status logs for failed push notification deliveries ("status": "FAILURE").
2. Check the failed push notification delivery logs for any other platform response codes.
3. Follow the Recommended Action that's listed for the codes in the Downstream message error response codes section on the Firebase website.

For more information on FCM error codes and troubleshooting best practices, see ErrorCode on the Firebase website.

Troubleshoot messages that show successful delivery, but the message isn't displayed on the device

Either the device didn't receive the notification, or the notification isn't displayed in the system's notification tray. To determine the cause, include log statements in the application's message handler.

If messages are received as a notification payload but not as a data payload, then review the message handler in the client application code. Only the client's application code handles data notifications. Make sure that the notification is pushed to the system's notification tray.

For more information, see Handling messages on the Firebase website.

Troubleshoot Android devices

For Android devices, use the FCM Android diagnostics page to check the delivery status and further troubleshoot the issue. To open the FCM diagnostics page, dial *#*#426#*#* from the Google dialer. For more information, see FCM Android diagnostics on the Firebase website.

Related information

How do I create an Android platform application in Amazon SNS for push notifications?

Monitoring Amazon SNS topics using CloudWatch

Mobile push notifications

How do I create an APNs platform application for sending push notifications in Amazon SNS using the AWS CLI?