Mobile Push Troubleshooting

If you are experiencing issues publishing to devices via the PubNub Mobile Gateway, the following are debug techniques that may help narrow down the issue. Each of them circumvents Mobile Push Notifications feature logic to ensure that your device push tokens, applications, and registration/certificates are configured correctly.

Regardless if it's a PubNub issue or not, we're always happy to help! Sending us the results of the following tests when opening a support ticket, may save a lot time isolating the root cause of your issue.

If your are testing your mobile push notifications and not receiving them in your test devices, reconfirm the following:

  • You're using the proper PubNub API keys (publish and subscribe keys)
  • Mobile Push is correctly configured for those keys
  • Your app is correctly configured in your iOS or Android developer account
  • The test payloads are correctly formatted the necessary push payload keys/values

Debug Messages​

With PubNub, you can publish error messages to a special debug channel to troubleshoot push issues when the device token is invalid or the push payload if formatted incorrectly.

  1. Go to the PubNub Debug Console and subscribe to the -pndebug channel. If the channel you're publishing to is foo, subscribe to foo-pndebug.

  2. Add "pn_debug":true to your message payload at the top level.

    {
    "pn_debug":true,
    "pn_fcm":{
      "data":{
         "message":"hello"
      }
    },
    "pn_apns":{
      "aps":{
         "alert":"hello"
      },
      "pn_push":[
         {
            "push_type":"alert",
            "auth_method":"token",
    show all 26 lines

  3. Publish the message to channel foo. You can publish from your client, server or directly using the Debug Console. You should see useful error messages in the console.

Successful Device Registrations​

The following message shows how many devices successfully received the push notification that were registered for push messages on the target channel for each push service.

Devices found for push notification apns: 2 fcm

Errors​

The following messages are examples of the types of messages that FCM and APNs push services can send back to PubNub's mobile push notification gateway servers.

fcm Error: InvalidRegistration Devices: null
fcm WARNING error: NotRegistered, sub_key: sub-c-..., channel: my_channel, reg_id: APA91bHRRxfHHB_T0AVojoJx..., timetoken: 14567269547473296
apns INFO Certificate for sub-c-... valid (expiration: Sep 14 08:58:26 2016 GMT)
apns ERROR Error on APNs send for subkey sub-c-... / channel gone_fishing / device 2a0a6234ffdb85df6624cf0546...: invalid token

All the above messages can be sent to your server using Push Webhooks. Refer to Push Webhooks for more information.

Push Webhooks​

Push Webhooks can be setup from the Admin Portal. Once configured, your endpoint will receive webhook events for push errors or when push devices are unregistered/removed.

  • A push device is removed:

    {
       "sub_key":"sub-c-e1559b02-3320-11ea-b686-76f717eaed2c",
       "timestamp":"16007987966269679",
       "platform":"apns2",
       "action":"remove",
       "device":"f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22f3b26d22"
    }

  • A message is sent with an invalid APNs2 payload:

    {
       "type":"error",
       "platform":"apns",
       "timestamp":"16008987759817415",
       "msg":"APNs2 payload error: pn_push must be a list",
       "channel":"mangai2",
       "sub_key":"sub-c-4db1663a-b2f4-11e9-ab7b-1ef11a8ab0d1",
       "devices":""
    }

  • An FCM device is updated with a new device token:

    {
    "sub_key" : "sub-c-...",
    "action" : "update",
    "old_device": "APA91bEgK4D",
    "device" : "ta28zYhV",
    "platform" : "gcm",
    "timestamp" : 1441230130
    }

Check Device Registration​

You can also check if the device is still registered to channels after you publish the push notification using a simple REST URL in the browser.

In the following cURL command, push_type is either gcm apns2 or apns, and device_reg_token is the device's registration token. This returns all channels the device is still registered for push notification for the push type provided.

curl 'http://ps.pndsn.com/v1/push/sub-key/{your_sub_key}/devices/{device_token}?type={push_type}'

Example of response:

["channel1","channel2","channel3"]

If the returned list is empty, then there was likely a device registration token issue (invalid token or device not registered, for example). This might happen because the device token was reported as invalid by the push notification services (APNs or FCM) and PubNub, in turn, unregisters that device token from all channels. Using the -pndebug channel should reveal the reason for this to you.

Check FCM Payload​

When you configure and implement FCM into your application, you may not see the mobile push notifications that you're sending. Before you start PubNub mobile push troubleshooting, ensure that you're sending and receiving the intended FCM type. The following is an excerpt from the Firebase documentation:

"With FCM, you can send two types of messages to clients: Data or Notification. Notification messages are sometimes thought of as display messages. These are handled by the FCM SDK and displayed automatically. Data messages, which are handled by the client app. Notification messages contain a predefined set of user-visible keys. Data messages, by contrast, contain only your user-defined custom key-value pairs. Notification messages can contain an optional data payload. Maximum payload for both message types is 4KB, except when sending messages from the Firebase console, which enforces a 1024 character limit."

Following the above, it could be that your app is pulling or sending the wrong message type. For example, you could use one, the other or both of these message keys in your FCM message payload: data or notification.

{
  "pn_fcm" : {
    "notification": {
      "title":"Portugal vs Denmark",
      "body":"great match!"
    },
    "data" : {
      "room" : "Portugal vs Denmark",
      "body" : "great match!"
    }
  }
}

You only need either data or notification (perhaps both depending on your use case) but it does matter if you only send data because your code is explicitly responsible for displaying the push notification, whereas notification will be automatically displayed by Android.

Background Notifications​

If a device has been registered to receive Mobile Push messages via FCM or APNs, is running a native PubNub Android or iOS client SDK, and is natively subscribed to the same associated channel via the native PubNub client SDK, it will receive the message twice—once via the Mobile Push Notifications feature, and once via the native PubNub client SDK. You'll need to manually add logic to de-duplicate.

Testing Mobile Push Notifications Without PubNub​

Most times it's not PubNub that causes the push notification issues. Often it's an invalid registration token (APNs or FCM), a device with two valid registration tokens or the push service certificate or key is no longer valid. Testing mobile push notifications without PubNub getting involved is the best way to eliminate, or hone in on, the area of probable fault.

Testing FCM​

Use the following cURL command (taken from Google's FCM page) to publish a message to FCM, completely circumventing PubNub infrastructure. Note that the command requires a registration ID.

Legacy FCM:

curl --header "Authorization: key=<API_KEY>"\
  --header Content-Type:"application/json"\
  https://fcm.googleapis.com/fcm/send\
  -d "{\"registration_ids\":[\"ABC\"]}"

HTTP v1:

Refer to Firebase docs on how to generate an OAuth access token and then send a push notification.

There are a few additional online tools for testing FCM mobile push notifications and one native Mac app.

Testing APNs​

Use this script to publish a message to APNs, completely circumventing PubNub infrastructure. Note that it requires an APNs certificate and an iOS device token.

For APNs, you can run a Python script that uses your push certificate (.pem file) to verify that the certificate is valid. Optionally, you can specify a device registration token to which test mobile push notifications will be sent.

For more rich UI/UX tools, you can find APNs test apps for the Mac (in the App Store) in addition to online web apps. Also, refer to Apple's Troubleshooting Mobile Push Notifications.

Last updated on
On this page