✨ 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

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.

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.

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

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