DOCS
Ask AI

Mobile push notifications

Mobile Push Notifications bridges native PubNub publishing with two third-party push services, Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM). A channel message reaches a device through PubNub's normal real-time path only while that device stays connected. Push closes that gap. It forwards the same message to APNs or FCM, so the device's operating system can surface it even when the app is in the background or the socket is closed.

The delivery model​

Mobile push works by registering device tokens against channel names, then watching publishes on those channels for a push payload. A client app publishes a message with a push payload to a channel. PubNub's Push Gateway reads the pn_apns or pn_fcm key and looks up the device tokens registered on that channel. The gateway forwards the request to APNs for APNs tokens and to FCM for FCM tokens. The provider then delivers the notification to the device's operating system, which displays it.


A publish carries the push forward on its own. It needs no separate send step, no queue, and no background job you run yourself.

Registration is scoped to individual channels​

Registering a device associates its token with one channel name. Channel groups aren't a valid registration target and can't be used to bulk-register a device or as a push destination. Your application might want a device to receive push for a whole set of channels, whether that's ten rooms or a full feed. It registers that same token on each channel individually.

This is a structural limit of the feature, not a configuration choice. It shapes how registration logic scales, because a device that joins many channels needs one registration call per channel rather than one call for the whole group.

To find the mobile push API reference for your platform, see Available SDKs.

What triggers a push and what doesn't​

A push notification always starts as a published event that carries a push payload: pn_apns for APNs, pn_fcm for FCM. Use both when the same publish should reach devices on either platform. PubNub's gateway inspects every published event on a push-enabled channel for these keys. If they're absent, the event delivers over pub/sub as usual and never touches the gateway.

The trigger is a key inside the payload, not a separate API. Push follows the same channel routing and message-type rules that already govern that channel. With Access Manager, a client needs read permission to register or remove its device from a channel. Push delivery itself does not require an additional Access Manager permission.

Whether a publish can trigger a push depends on its publish type:

  • Messages. A message with a pn_apns or pn_fcm key in its payload triggers a push.
  • File messages. A file message can carry a push payload alongside the uploaded file. It triggers a push the same way a regular message does.
  • Signals. A signal never triggers a push, even when its payload contains a push key. Signals are the lightweight publish type that PubNub doesn't store.

To send each publish type in code, see Send different message types.

Why the same event can arrive twice​

Push and live in-app delivery are independent paths that PubNub does not reconcile for you. A device can be both push-registered on a channel and actively subscribed to it. That device sits on both delivery paths at once, so a single publish can reach it twice. It arrives immediately as a subscribed message over the open connection, then again, moments later, as a push notification from APNs or FCM. Neither path knows about the other, so PubNub doesn't suppress either one on the assumption that the other already delivered.

If an application needs to show the event only once, de-duplicating it is its own responsibility. A common approach is to recognize that a foregrounded, actively subscribed session doesn't need the push notification a backgrounded one would.

This is also why the platform push APIs matter. When a user is active in the app, they already receive the live message through their subscription, so a push notification's job of waking a disconnected client is already done. To avoid a redundant alert, mute the notification at the OS level for that state instead of muting the real-time message. Other subscribers, and other sessions of the same user, still need that message.

Self-notification​

A single person often connects with the same User ID from more than one device: a phone and a tablet, or a phone and a desktop client. When one of those devices publishes a push-triggering message, all registered devices on that channel are, by default, eligible for the push, including the device that just published it. Getting a push for a message your own device just sent is rarely useful and often disruptive, so PubNub's push payload supports excluding specific device tokens from a given publish.

An application that wants to avoid this self-notification excludes it directly. It adds the publishing device's own token, and the tokens of any of that same user's other devices it also wants to spare, to the exclusion list for that publish. This is a per-publish decision, not a standing registration setting, because whether self-notification is unwanted depends on which device is sending, and that can change from one publish to the next.

Debugging without instrumenting your app​

Push failures are otherwise invisible. An invalid device token, a malformed payload, or a provider-side rejection from APNs or FCM doesn't surface as an error on the publish call. The publish itself succeeded. Only the downstream push failed.

To close that gap, PubNub publishes push-specific diagnostic messages to a companion channel named {channelName}-pndebug for every channel with push enabled. Subscribing to that companion channel gives visibility into push-layer failures without adding logging or error handling to your own send path. See Debug push notification messages for how to read and interpret what shows up there.

Configuration is a keyset-level setting​

Mobile push is enabled and credentialed per keyset in the Admin Portal, not per channel or per publish. Enabling the feature is one part of the setup. The other is supplying provider credentials so PubNub can authenticate to APNs and FCM on your behalf. For FCM, that's a private key file generated in Firebase. For APNs, that's a Team ID, an Auth Key ID, and an uploaded .p8 token file.

ItemLimit
Push credentials per keyset1 APNs certificate and 1 FCM key
Push notification payload size2 KB for APNs, 4 KB for FCM

Because credentials live at the keyset level, every channel and every publish on that keyset shares the same APNs and FCM identity. There's no per-channel or per-app override. An application that needs to push through a different set of provider credentials needs a separate keyset.

Next steps​

Was this page useful?

Last updated on