← Plugins  /  Push Notifications

iOS · APNs Android · FCM 📦 npm ⚖️ MIT

Zero-config push notifications for Apache Cordova. Firebase Cloud Messaging on Android, native APNs on iOS — and you only write JavaScript. Most push plugins make you hand-edit Gradle files, AppDelegates, manifests and entitlements; this one does the boring wiring for you.

What it wires for you

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

🍏 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) — you'll use it on your push server.
2. Add the iOS platform and open the workspace: cordova platform add ios then open platforms/ios/*.xcworkspace.
3. Under Signing & Capabilities, select your Team.
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.
});

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.

Events — on() / once() / off()

The notification payload includes title, body, data (your custom key/values), foreground, tap, and on iOS badge, sound and messageId.

Other methods

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 to receive custom key/values in the notification event's data field. On iOS, keys outside the aps object are delivered the same way.

Compatibility