Push Notifications

Handle Firebase Cloud Messaging push notifications on iOS and Android.

iOS, supported
Android, supported
Web, not supported

Package: @capnative/capacitor-push-notifications
npm version: 8.1.3
Capacitor: 8.x · MIT

API checked against the repository README, TypeScript definitions, and npm on October 25, 2026.The README marks this major as maintained.

Install

Peer dependency: @capacitor/core >= 8.0.0

bash

npm install @capnative/capacitor-push-notifications
npx cap sync

Usage

typescript

import { PushNotifications } from '@capnative/capacitor-push-notifications';

await PushNotifications.addListener('registration', ({ value }) => {
  console.log('FCM token:', value);
});

await PushNotifications.addListener('registrationError', ({ error }) => {
  console.error('FCM registration failed:', error);
});

await PushNotifications.addListener('pushNotificationReceived', (notification) => {
  console.log('Notification received:', notification);
});

await PushNotifications.addListener('pushNotificationActionPerformed', (action) => {
  console.log('Notification action:', action);
});

const permission = await PushNotifications.requestPermissions();
if (permission.receive === 'granted') {
  await PushNotifications.register();
}

Platform setup

Configure Firebase Cloud Messaging before calling register.

Android

Add google-services.json to android/app/.

The plugin manifest merges these entries, so they do not need to be copied by hand:

permission android.permission.POST_NOTIFICATIONS
service com.capnative.pushnotifications.MessagingService (android:exported="false") for the action com.google.firebase.MESSAGING_EVENT

The Android library depends on the Firebase BoM com.google.firebase:firebase-bom:34.0.0 and on com.google.firebase:firebase-messaging. Minimum version is API 24.

TODO: the README does not mention applying the Google Services Gradle plugin (com.google.gms.google-services) in the app module. Use Firebase’s Android setup if google-services.json is not being read.

iOS

Add GoogleService-Info.plist to the app target. Enable the Push Notifications capability and Background Modes (Remote notifications). Upload the APNs authentication key to Firebase. Minimum version is iOS 15.

TODO: the README does not include Info.plist XML for background modes. It tells you to enable the Xcode capabilities above.

Web

Every method rejects with Capacitor’s unimplemented error: Push notifications are not implemented on web.

API

Method signatures match PushNotifications in the plugin repository. Import it from @capnative/capacitor-push-notifications.

checkPermissions()

Checks whether push notification permission is granted.

Signature

checkPermissions() => Promise<PermissionStatus>

Returns Promise<PermissionStatus>

requestPermissions()

Requests permission to receive push notifications and returns the resulting status.

Signature

requestPermissions() => Promise<PermissionStatus>

Returns Promise<PermissionStatus>

register()

Starts FCM registration. The resulting token is emitted by the registration event. Registration failures are emitted by registrationError.

Signature

register() => Promise<void>

unregister()

Unregisters from push notifications and deletes the FCM token.

Signature

unregister() => Promise<void>

getToken()

Retrieves the current FCM registration token.

Signature

getToken() => Promise<Token>

Returns Promise<Token>

subscribeToTopic()

Subscribes this app installation to an FCM topic.

Signature

subscribeToTopic(options: { topic: string }) => Promise<void>

Param	Type	Description
options.topic	string	FCM topic name.

unsubscribeFromTopic()

Unsubscribes this app installation from an FCM topic.

Signature

unsubscribeFromTopic(options: { topic: string }) => Promise<void>

Param	Type	Description
options.topic	string	FCM topic name.

getDeliveredNotifications()

Retrieves notifications currently displayed in the system notification center.

Signature

getDeliveredNotifications() => Promise<DeliveredNotifications>

Returns Promise<DeliveredNotifications>

removeDeliveredNotifications()

Removes the specified notifications from the system notification center. Pass the result of getDeliveredNotifications() or an object containing a subset of its notifications.

Signature

removeDeliveredNotifications(delivered: DeliveredNotifications) => Promise<void>

Param	Type	Description
delivered	DeliveredNotifications	Notifications to remove.

removeAllDeliveredNotifications()

Removes all notifications currently displayed in the system notification center.

Signature

removeAllDeliveredNotifications() => Promise<void>

removeAllListeners()

Removes all listeners registered for this plugin.

Signature

removeAllListeners() => Promise<void>

Events

registration

Fires with the FCM registration token.

Signature

addListener('registration', (token: Token) => void) => Promise<PluginListenerHandle>

Payload: Token.value is the Firebase Cloud Messaging registration token.

registrationError

Fires when FCM registration fails.

Signature

addListener('registrationError', (error: RegistrationError) => void) => Promise<PluginListenerHandle>

Payload: RegistrationError.error is the registration error detail.

pushNotificationReceived

Fires for notifications received while the app is active.

Signature

addListener('pushNotificationReceived', (notification: PushNotification) => void) => Promise<PluginListenerHandle>

Payload: PushNotification

pushNotificationActionPerformed

Fires for notification interactions, including taps.

Signature

addListener('pushNotificationActionPerformed', (action: ActionPerformed) => void) => Promise<PluginListenerHandle>

Payload: ActionPerformed. A standard notification tap is reported as actionId "tap".

Interfaces

PermissionStatus

Property	Type	Description
receive	PermissionState	Current permission state for receiving push notifications.

Token

Property	Type	Description
value	string	Firebase Cloud Messaging registration token.

PushNotification

Property	Type	Description
idoptional	string	Optional platform notification identifier.
titleoptional	string	Optional notification title.
bodyoptional	string	Optional notification body.
data	Record<string, any>	Notification data payload.

DeliveredNotification

Property	Type	Description
id	string	Platform notification identifier.
tagoptional	string	Optional Android notification tag.
titleoptional	string	Optional notification title.
bodyoptional	string	Optional notification body.
data	Record<string, any>	Notification data payload.

DeliveredNotifications

Property	Type	Description
notifications	DeliveredNotification[]	Notifications currently displayed in the system notification center.

ActionPerformed

Property	Type	Description
actionId	string	Identifier for the action performed on the notification. A standard tap is "tap".
notification	PushNotification	The notification that was interacted with.

RegistrationError

Property	Type	Description
error	string	Registration error details.

PluginListenerHandle

Property	Type	Description
remove	() => Promise<void>	Removes this listener.

Type aliases

PermissionState
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'