Skip to content

About

Updated Version 06-2026

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

🔔 cordova-plugin-push-notification-v2026

Zero-config push notifications for Apache Cordova.
Firebase Cloud Messaging on Android · native APNs on iOS · you only write JavaScript.

npm version MIT License Platforms cordova-android cordova-ios GitHub stars

⭐ If this plugin saves you time, please give it a star on GitHub — it really helps! ⭐


✨ Why this plugin?

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.


📦 Installation

cordova plugin add cordova-plugin-push-notification-v2026

Requires cordova-android ≥ 14 (tested on 15) and cordova-ios ≥ 7 (tested on 8.1).


🤖 Android setup (Firebase Cloud Messaging)

  1. Create a project in the Firebase Console and add an Android app using your app's package id (the id in config.xml).

  2. Download google-services.json.

  3. 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.

  4. Build & run:

    cordova run android

💡 Other accepted locations: res/, www/, or a google-services/ folder. Keep google-services.json out of version control (it's already in .gitignore).


🍏 iOS setup (Apple Push Notification service)

The plugin adds the Push Notifications capability, the aps-environment entitlement and the remote-notification background mode automatically. You only need a signing identity:

  1. In the Apple Developer portal, create an APNs Auth Key (.p8) (recommended) — you'll use it on your push server.

  2. Add the iOS platform and open the workspace:

    cordova platform add ios
    open platforms/ios/*.xcworkspace
  3. Under Signing & Capabilities, select your Team. (The Push Notifications capability is already present.)

  4. Run on a physical device — the simulator can't receive remote pushes:

    cordova run ios --device

🚀 Quick start

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. 🎉


📖 API

All methods return a Promise. The module is clobbered onto cordova.plugins.pushNotification.

register(options?) → Promise<RegistrationResult>

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';
}

Events — on(event, cb) / once(event, cb) / off(event, cb?)

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;
}

Other methods

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

📤 Sending a notification (server side)

Android / cross-platform via FCM HTTP v1

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 data alongside notification) to receive custom key/values in the notification event's data field.

iOS via APNs (token-based auth, .p8 key)

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_TOKEN

Keys outside the aps object are delivered as data in the notification event.


🧪 Sample app

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 --device

See example/README.md for details.


🛠 Troubleshooting

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 to api.push.apple.com. Debug builds use development; send to api.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.


📋 Compatibility

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

🤝 Contributing

Issues and PRs are very welcome! If you find a bug or want a feature, open an issue.

⭐ Star the repo

If this plugin helped you ship faster, please star it on GitHub — it motivates continued maintenance and helps other developers find it. Thank you! 🙏

📄 License

MIT © dedrisproject

About

Updated Version 06-2026

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages