Zero-config push notifications for Apache Cordova.
Firebase Cloud Messaging on Android · native APNs on iOS · you only write JavaScript.
⭐ If this plugin saves you time, please give it a star on GitHub — it really helps! ⭐
Most push plugins make you hand-edit Gradle files, AppDelegates, manifests and entitlements. This one does the boring wiring for you:
| Task | Other plugins | This plugin |
|---|---|---|
Apply the Firebase google-services Gradle plugin |
manual | ✅ automatic |
Copy google-services.json into the build |
manual | ✅ automatic (build hook) |
Request POST_NOTIFICATIONS (Android 13+) |
manual | ✅ automatic |
| Add the iOS Push Notifications entitlement | manual (Xcode) | ✅ automatic (plugin.xml) |
Add the remote-notification background mode |
manual | ✅ automatic |
| Foreground / background / tap handling | varies | ✅ unified events |
| TypeScript types | rarely | ✅ included |
The only thing you provide is your Firebase / Apple credentials. Everything else is one register() call.
cordova plugin add cordova-plugin-push-notification-v2026Requires cordova-android ≥ 14 (tested on 15) and cordova-ios ≥ 7 (tested on 8.1).
-
Create a project in the Firebase Console and add an Android app using your app's package id (the
idinconfig.xml). -
Download
google-services.json. -
Drop it in your project root (next to
config.xml):my-app/ ├── config.xml ├── google-services.json ← here └── www/The plugin's build hook copies it into
platforms/android/app/on every build and auto-applies the Firebase Gradle plugin. No Gradle editing required. -
Build & run:
cordova run android
💡 Other accepted locations:
res/,www/, or agoogle-services/folder. Keepgoogle-services.jsonout of version control (it's already in.gitignore).
The plugin adds the Push Notifications capability, the aps-environment entitlement and the remote-notification background mode automatically. You only need a signing identity:
-
In the Apple Developer portal, create an APNs Auth Key (.p8) (recommended) — you'll use it on your push server.
-
Add the iOS platform and open the workspace:
cordova platform add ios open platforms/ios/*.xcworkspace -
Under Signing & Capabilities, select your Team. (The Push Notifications capability is already present.)
-
Run on a physical device — the simulator can't receive remote pushes:
cordova run ios --device
document.addEventListener('deviceready', async () => {
const push = cordova.plugins.pushNotification;
// Fires for every incoming notification (foreground, background-tap, etc.)
push.on('notification', (n) => {
console.log('Notification:', n.title, n.body, n.data);
if (n.tap) {
// The user tapped the notification — navigate accordingly.
}
});
push.on('error', (e) => console.error('Push error:', e.message));
// Requests permission, registers with FCM/APNs and returns the token.
const { token, platform, registrationType } = await push.register();
console.log(`Registered on ${platform} (${registrationType}):`, token);
// Send `token` to your backend to target this device.
});That's the whole integration. 🎉
All methods return a Promise. The module is clobbered onto cordova.plugins.pushNotification.
Requests permission, registers with FCM/APNs, starts event delivery and resolves with the device token.
interface RegisterOptions {
alert?: boolean; // iOS — request alert permission (default true)
badge?: boolean; // iOS — request badge permission (default true)
sound?: boolean; // iOS — request sound permission (default true)
clearBadge?: boolean; // iOS — reset badge on launch (default true)
android?: {
channelId?: string; // default "push_default"
channelName?: string; // shown in system settings
importance?: 'high' | 'default' | 'low' | 'min';
forceShow?: boolean; // show a tray notification even in foreground
};
}
interface RegistrationResult {
token: string;
platform: 'android' | 'ios';
registrationType: 'FCM' | 'APNS';
}| Event | Payload | When |
|---|---|---|
registration |
{ token, platform, registrationType } |
Token obtained / changed |
notification |
see below | A push arrives or is tapped |
tokenRefresh |
{ token } |
The FCM token rotated |
error |
{ message, code? } |
Something failed |
notification payload
{
title?: string;
body?: string;
data: Record<string, any>; // your custom key/values
foreground: boolean; // received while app was visible
tap: boolean; // user tapped the notification
badge?: number; // iOS
sound?: string;
messageId?: string;
}| Method | Platform | Description |
|---|---|---|
getToken() |
both | Resolve the current device token |
subscribe(topic) |
Android | Join an FCM topic (no-op on iOS) |
unsubscribe(topic) |
Android | Leave an FCM topic |
unregister() |
both | Stop notifications and delete the token |
setBadge(n) / getBadge() |
iOS | Manage the app icon badge |
clearNotifications() |
both | Remove delivered notifications |
hasPermission() |
both | true if notifications are authorised |
requestPermission() |
both | Explicitly prompt for permission |
curl -X POST \
https://fcm.googleapis.com/v1/projects/YOUR_PROJECT_ID/messages:send \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"message": {
"token": "DEVICE_FCM_TOKEN",
"notification": { "title": "Hello 👋", "body": "Sent via FCM v1" },
"data": { "screen": "inbox", "id": "42" }
}
}'Use a data payload (or
dataalongsidenotification) to receive custom key/values in thenotificationevent'sdatafield.
curl -v \
--http2 \
--header "apns-topic: com.dedrisproject.pushdemo" \
--header "apns-push-type: alert" \
--header "authorization: bearer $APNS_JWT" \
--data '{
"aps": { "alert": { "title": "Hello 👋", "body": "Sent via APNs" }, "sound": "default", "badge": 1 },
"screen": "inbox", "id": "42"
}' \
https://api.push.apple.com/3/device/DEVICE_APNS_TOKENKeys outside the
apsobject are delivered asdatain thenotificationevent.
A complete, runnable demo for Android and iOS lives in example/ — register, receive, topics, badge and a live event log.
cd example
./setup.sh # adds the plugin + both platforms
cordova run android # or: cordova run ios --deviceSee example/README.md for details.
Android build fails: "File google-services.json is missing"
Place google-services.json in your project root (next to config.xml) and rebuild. The plugin warns at build time if it can't find it.
No token / "Firebase not initialised"
The package id in google-services.json must exactly match your config.xml id. Re-download the file from Firebase if you changed the id.
iOS: not receiving pushes
- Test on a real device (the simulator can't receive remote pushes).
- Make sure a signing Team is selected and the provisioning profile includes the Push Notifications capability.
- Production builds use
aps-environment = production; send toapi.push.apple.com. Debug builds usedevelopment; send toapi.sandbox.push.apple.com.
Android 13+: notifications don't appear
register() requests the POST_NOTIFICATIONS runtime permission. If the user previously denied it, send them to system settings to re-enable.
| Component | Version |
|---|---|
| Cordova CLI | ≥ 12 |
| cordova-android | ≥ 14 (tested 15) |
| cordova-ios | ≥ 7 (tested 8.1) |
| Android min SDK | 24 |
| iOS deployment target | 13.0 |
| Firebase Messaging | 24.x |
Issues and PRs are very welcome! If you find a bug or want a feature, open an issue.
If this plugin helped you ship faster, please star it on GitHub — it motivates continued maintenance and helps other developers find it. Thank you! 🙏
MIT © dedrisproject