---
source_url: https://www.pubnub.com/docs/integrations/mobile-push-notifications/overview
title: Mobile push notifications
updated_at: 2026-09-30T07:20:08.000Z
---

# Mobile push notifications

## Documentation index

To discover more PubNub resources:

1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format.
2. Identify relevant URLs from that index.
3. Fetch the target pages.

Do not assume a path exists, always check the index first.

Mobile Push Notifications bridges native PubNub [publishing](https://www.pubnub.com/docs/pub-sub/publish/overview.md) with two third-party push services, Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM). A [channel](https://www.pubnub.com/docs/architecture/core-concepts.md#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.

```mermaid
flowchart TB
    APP["<b>Client app</b>"]

    subgraph PN["PubNub"]
        GW["<b>Push Gateway</b><br/>reads pn_apns / pn_fcm"]
        LOOKUP["<b>Registered device tokens</b><br/>for this channel"]
    end

    APNS["<b>APNs</b>"]
    FCM["<b>FCM</b>"]
    DEVICE["<b>Device OS</b><br/>shows the notification"]

    APP -->|"publish() with<br/>push payload"| GW
    GW --> LOOKUP
    LOOKUP -->|forwards request| APNS & FCM
    APNS --> DEVICE
    FCM --> DEVICE

    class GW emphasis
    class LOOKUP muted
    class APNS,FCM external
    class PN platform
```

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](https://www.pubnub.com/docs/getting-started/available-sdks.md).

## 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](https://www.pubnub.com/docs/security/access-control/overview.md), 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](https://www.pubnub.com/docs/data-storage/files/overview.md) can carry a push payload alongside the uploaded file. It triggers a push the same way a regular message does.
* **Signals.** A [signal](https://www.pubnub.com/docs/pub-sub/publish/send-different-message-types.md#send-a-signal-instead-of-a-message) 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](https://www.pubnub.com/docs/pub-sub/publish/send-different-message-types.md).

## 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](https://www.pubnub.com/docs/architecture/core-concepts.md#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](https://www.pubnub.com/docs/integrations/mobile-push-notifications/debug-push-notification-messages.md) 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](https://admin.pubnub.com/), 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.

| Item | Limit |
| --- | --- |
| Push credentials per keyset | 1 APNs certificate and 1 FCM key |
| Push notification payload size | 2 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

* [Send push notifications on iOS](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-ios.md). Walk through registering an iOS device for APNs push and sending a first notification.
* [Send push notifications on Android](https://www.pubnub.com/docs/integrations/mobile-push-notifications/send-push-notifications-android.md). Walk through registering an Android device for FCM push and sending a first notification.
* [Debug push notification messages](https://www.pubnub.com/docs/integrations/mobile-push-notifications/debug-push-notification-messages.md). Read the `-pndebug` companion channel to see why a push failed.
* [Forward push errors and device removals to your endpoint](https://www.pubnub.com/docs/integrations/mobile-push-notifications/set-up-push-webhooks.md). Send push errors and device-removal events to your endpoint.
* [Check push device registration](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-push-device-registration.md). Confirm which channels a device token is currently registered on.
* [Check the FCM payload](https://www.pubnub.com/docs/integrations/mobile-push-notifications/check-fcm-payload.md). Verify that an FCM push payload is shaped the way Firebase expects.
* [Test mobile push notifications externally](https://www.pubnub.com/docs/integrations/mobile-push-notifications/test-mobile-push-notifications-externally.md). Send a push outside your application to isolate whether a failure is in your code or in the provider setup.
* [Available SDKs](https://www.pubnub.com/docs/getting-started/available-sdks.md). Check whether your platform's SDK supports mobile push before you build against it.

Last updated at: 2026-09-30T07:20:08.000Z