Integrations FAQ

13 questions on this page

Short answers to common questions about mobile push notifications.

Which push notification services does PubNub support?

PubNub mobile push notifications support Apple Push Notification service (APNs) for iOS devices and Firebase Cloud Messaging (FCM) for Android devices.

PubNub forwards a published message to APNs, FCM, or both, depending on whether its payload has a pn_apns key, a pn_fcm key, or both. For how the forwarding works, see Mobile push notifications.

Which SDKs support mobile push notifications?

Every SDK that can publish, and the REST API, can send a push notification, because a push notification is an ordinary publish with a pn_apns or pn_fcm key.

Registering a device token on a channel needs the Mobile Push API. An SDK supports it if its API reference has a Mobile Push page. If yours doesn't, register devices through the REST API.

For the full list of SDKs, see Available SDKs.

How do I register a device for push notifications on a channel?

Register the device token on the channel with the Mobile Push API of your SDK, after you enable Mobile Push Notifications and add your Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM) credentials to the keyset. A registration pairs one device token with one channel, so a publish to that channel can become a push to that device. If you use Access Manager (v2/v3), the client needs read permission on the channel.

Register the same token on each channel the device should receive push for, because channel groups aren't a valid registration target.

For the steps and code, see Register the device token on a channel for iOS and Register the token on a PubNub channel for Android. To confirm which channels a token is registered on, see Check push device registration.

How many channels can I register for push per device and per REST call?

Mobile Push Notifications has no limit on the number of channels you register per device or per registration call. The whole registration request must fit within the same size limit as publish. For all push limits, see API limits.

When does PubNub send a message and when a push notification?

A publish always reaches the channel's subscribers as a message. It also becomes a push notification only when its payload has a pn_apns or pn_fcm key and the channel has devices registered for push.

When the keys are present, subscribers still receive the whole message, including those keys, and only the content of pn_apns goes to APNs and the content of pn_fcm goes to FCM. A signal never triggers a push, even if its payload has a push key.

A device that is both subscribed and registered can receive the same publish twice, once as a message and once as a push. For the details, see What triggers a push and what doesn't.

Are push notifications stored in message history?

Yes, if Message Persistence is enabled on the keyset. A push notification is an ordinary publish with a push payload, so PubNub stores it like any other message.

Message Persistence must be enabled on the keyset before you store or read history, and new keysets don't enable it by default.

Can I push to sandbox and production with the same keyset?

Yes, for APNs. Each device registration and each pn_push target in the payload names an APNs environment:

• development for builds installed by Xcode.
• production for TestFlight and App Store builds.

Keysets are usually split by environment anyway, so a key compromised or misconfigured in one environment can't reach another. For how to map keysets to environments, see Protecting your keys.

What does a valid APNs payload look like?

A valid APNs payload is a pn_apns object that holds an aps object and a pn_push array. The aps object holds the notification, such as the alert text. The pn_push array names the push type and the APNs topic and environment to target. The whole payload must fit within the mobile push limits. For a complete example, see Publish a message with a push payload.

Why am I not receiving push notifications?

A publish can succeed even when the push through Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM) fails, so check the push setup. The most common causes are:

• Mobile Push Notifications isn't enabled on the keyset, or the keys in your app belong to a different keyset, for example the shared demo keys.
• The APNs or FCM credentials on the keyset are wrong. The FCM private key must come from the same Firebase project as your app.
• The device token isn't registered on the channel you publish to, or the token changed after you registered it.
• The payload has no pn_apns or pn_fcm key, or the payload is invalid.
• The APNs environment doesn't match the build. Use development for builds installed by Xcode and production for TestFlight and App Store builds.
• The app is in the foreground, or notifications are turned off for the app on the device.

To see the errors APNs and FCM return to PubNub, subscribe to the channel's -pndebug companion channel. See Debug push notification messages. To find out whether the problem is in your provider setup or in PubNub, see Test mobile push notifications externally. For platform-specific checks, see the troubleshooting sections for iOS and Android.

Can I send large messages through APNs?

No. For APNs, the push payload is limited to 4,096 bytes, or 5,120 bytes for VoIP notifications, counted on the whole APNs payload. PubNub checks this limit before sending. A larger payload can't go through Apple Push Notification service (APNs) as a push.

For how the push limits compare with the publish limits, see API limits.

Which APNs push types can I use?

Set push_type in the pn_push array to the APNs push type that matches your aps payload, such as alert for a notification the user sees, background for a silent update, or voip for an incoming call. For every push type Apple defines and when to use it, see Apple's Sending notification requests to APNs. For where push_type goes in the payload, see Publish a message with a push payload.

How do I stop the sender from getting a push for their own message?

Add the sender's device token to the exclusion list in the push payload of each message you publish, and PubNub skips that device.

• APNs: put the token in excluded_devices in the pn_push target.
• FCM: put it in pn_exceptions inside pn_fcm.

You can list more than one token, for example to skip all of the sender's devices.

For examples, see Exclude the sender's device for iOS and Publish a message with an FCM push payload for Android. To skip the sender's own messages in real time, see Exclude your own published messages.

How do I keep an iOS device registered when its token changes?

Apple can invalidate a device token, for example after you change your app's APNs setup. Check the token on every cold start of the app.

In didRegisterForRemoteNotificationsWithDeviceToken, compare the token APNs returns with the one you saved:

• If it changed, remove the old token from PubNub, register the new token on your channels, and save it.
• If it didn't change, the device is still registered and you don't need to do anything.

For the registration calls, see Receive the device token and Register the device token on a channel.