Push Basics

In-app messaging is powerful but you also may need Mobile Push Notifications. This feature delivers messages fast and reliably, whether the app is in the foreground or background on iOS and Android.

Hi! I’m Sarah - a Staff Software Engineer by day and a passionate gamer by night. I work at Indie Game Studio, where my team and I try to be the best in mobile gaming. Recently, we had the challenge of building an RTS game that would allow globally-distributed players to communicate in real time & stay up to date day and night. For that, we had to deliver a scalable in-game chat for live battles where players team up to form guilds and fight each other for resources and territory. We also wanted to keep the players engaged with mobile notifications for individual players (like “Rivals are conquering your land!”) and group broadcasts (“A new player is joining your guild”). However, we knew little about building a scalable chat with updates and didn’t have much time to do that either as we were busy designing maps and units.

We came across PubNub and immediately fell for it. PubNub offers a scalable, flexible tech stack with over 50 SDKs, including mobile support. Its primary use case is chat, so we knew immediately we were in good hands. PubNub also supports mobile push notifications for iOS and Android devices by offering integrations with third-party push notification services, including Firebase Cloud Messaging (FCM) and Apple Push Notification Service (APNs).

With PubNub at hand, game hosts could finally organize global weekly battles where players from all over the globe would come to win new resources or grow their in-game empire. These mass chats scale as expected and in case of any issues, there are troubleshooting guidelines and support to fall back to. Thanks to real-time updates, hosts noticed a significant increase in player engagement and retention. Players no longer fear missing out and can control their battlefield—even when someone might capture a base at any time.

Beware! Your base is being captured!

PubNub's Mobile Push Notifications bridges native PubNub publishing with third‑party push services, including Firebase Cloud Messaging (FCM) and Apple Push Notification Service (APNs). The push gateway lets you send important data and messages even when users are not active in your mobile app.

Pricing

Push notification transactions are included in PubNub’s Monthly Active Users (MAU) pricing model. For more information, visit our Pricing page.

How it works

After you enable Mobile Push Notifications, associate device tokens with PubNub channel names. When you publish to a channel, PubNub looks up registered tokens and forwards the push request to FCM or APNs for those devices. Behind the scenes, the feature establishes an authenticated connection to the providers based on your configuration.

Push notifications are delivered in the following manner:

1. First, publish a message on a channel with the push payload.
2. PubNub's Push Gateway checks device registrations and relays the message to push providers.
3. FCM/APNs providers deliver the push notification to one or more devices.

Configuration

Enable and configure Mobile Push Notifications on your app's keyset in the Admin Portal.

Public Admin Portal demo

Want to browse through the Admin Portal without creating an account? Explore it through the Public Demo that shows examples of most PubNub features for transport and logistics use case.

Option	Description
Firebase Cloud Messaging	Connection details for FCM when you use it as a push service provider to deliver push notifications to your application.
→ Private key file	Private key file downloaded from FCM.
Apple Push Credentials	Connection details for APNs when you use it as a push service provider to deliver push notifications to your application.
→ Team ID	10-character string generated by Apple that’s assigned to your team.
→ Auth Key ID	10-character key identifier generated by Apple.
→ Token file	Apple's authentication token signing key, like AuthKey_678PB6YGZ.p8.

Set up FCM/APNs credentials for your application. After you obtain credentials from Apple or Firebase, add them or upload a certificate in the Admin Portal.

Register devices

Register the device token (provided by the platform) with one or more PubNub channels. You can update registrations any time by adding channels or removing previously registered channels. This lets you curate channel‑specific messages and change targeted device lists in real time.

Registration scope

Mobile Push registration works with individual channels. Channel groups aren’t supported for registering devices or targeting Mobile Push Notifications. To target a set of channels, register the device token on each channel.

Send notifications

Include APNs, FCM, or both payloads when you publish a message. When PubNub finds pn_apns and pn_fcm, it retrieves device tokens registered on the target channel and forwards the push request to the appropriate provider.

• Create an APNs payload
• Create an FCM payload

Prevent self-notifications

When a user sends a message and then quickly backgrounds the app, they can receive a push notification for their own message. To prevent this, exclude the sender’s device token(s) in the push payload on each publish where you don’t want the sender to get a push.

• APNs: add the sender’s token to pn_apns.pn_push[].targets[].excluded_devices.
• FCM: add the sender’s token to pn_fcm.pn_exceptions.

If a user has multiple devices, include all of their device tokens so none of those devices receive the push. Users actively subscribed to the channel will still receive the real-time message; add client-side de-duplication if needed.

Receive notifications

After the PubNub Push Gateway forwards the request to APNs or FCM, those providers deliver notifications to devices. The push providers handle device delivery.

If the user is active in the app, the user receives the in‑app message via PubNub subscription, and a push may be unnecessary. Use platform APIs to mute the push notification instead of muting the real‑time message.

Troubleshooting

You can debug push notification issues by inspecting the messages published to a {channelName}-pndebug channel. For example, if you publish a message on channel ch1, the corresponding debug channel is ch1-pndebug. You can subscribe to a debug channel using the PubNub Debug Console to troubleshoot push errors like invalid device tokens or invalid push payload.

For more information about push troubleshooting, refer to Mobile Push Troubleshooting.