Example: Implement Mobile Push Notifications with the PubNub JavaScript SDK
Mobile push notifications let a PubNub message reach a device even when the app is in the background. PubNub Mobile Push Notifications connects PubNub publishing to Apple Push Notification service (APNs) and Firebase Cloud Messaging (FCM).
This guide uses the current JavaScript SDK API. It covers device registration, publishing a cross-platform push payload, opt-in and opt-out, and troubleshooting.
Prerequisites
• A PubNub app and keyset.
• The Mobile Push Notifications add-on enabled on the keyset.
• APNs credentials for iOS, or an FCM service-account private key for Android, configured in the Admin Portal.
• A native mobile app that requests notification permission and obtains a real APNs or FCM device token.
• The current JavaScript SDK (12.0.3 at the time of this update).
npm install pubnub
Never put a secret key or provider private key in a mobile app or browser bundle. Use only the publish and subscribe keys in client code. Keep secret credentials on a trusted server or in the Admin Portal.
Initialize PubNub
Use a stable, unique userId for the client. Replace the placeholders with the publish and subscribe keys from your keyset.
Register a device for push notifications
The device token comes from the native platform. Register it only after the user has granted notification permission.
iOS with APNs HTTP/2 (apns2)
APNs2 requires both the app bundle identifier (topic) and the APNs environment.
Android with FCM
FCM registration does not require an APNs environment or topic.
Handle registration errors and retry according to your app lifecycle. A provider token can rotate. Update the PubNub registration when the native SDK reports a new token.
Publish a push notification
Push delivery is triggered by a normal PubNub publish that contains a platform payload. The channel must be one of the channels registered for the device.
The APNs topic and environment in the payload must match the APNs registration and provider configuration. For FCM, data values must be strings and must not use Firebase-reserved keys.
If the sender should not receive its own push on another device, use the current payload options to exclude the sender device token. The sender can still receive the real-time PubNub message, so client-side de-duplication may be needed.
List and remove registrations
Pass the gateway every time. APNs2 also requires its environment and topic.
APNs2 registration options
For APNs2, add environment and topic to both calls.
Remove a device from all registered push channels
To remove a device from every registered push channel, use deleteDevice.
Implement opt-in and opt-out correctly
Permission prompts are platform-specific. Request permission through the native iOS or Android API, obtain the APNs or FCM token, then call addChannels only after consent. When the user opts out, call removeChannels for selected channels or deleteDevice for all channels.
Do not treat PubNub channel subscription and mobile-push registration as the same operation. A device can still receive real-time PubNub data while push delivery is disabled.
Browser Web Push is a different feature
PubNub Mobile Push Notifications targets native APNs and FCM device tokens. It does not register a browser PushSubscription or replace a service worker and VAPID Web Push implementation. For browser notifications, use the browser Push API and a service worker. PubNub can still publish the event that your server or worker uses to trigger that flow.
Troubleshooting
1. Confirm Mobile Push Notifications is enabled on the exact keyset used by the app.
2. Confirm the APNs topic, environment, and provider credentials match the app build.
3. Confirm the FCM service-account key belongs to the Firebase project used by the app.
4. Confirm the current device token is registered for the channel and remove stale tokens when they rotate.
5. Confirm the published message contains pn_apns, pn_fcm, or both. A normal message without a push payload does not produce a mobile push.
6. Inspect the channel's {channelName}-pndebug channel in the PubNub Debug Console for provider and payload errors.
7. Test on a physical device with the app in the background. Provider delivery and device power or network policy are outside PubNub real-time transport.
For the complete API surface, see the JavaScript Mobile Push Notifications API and Push Basics.
