capacitor-push-notifications

Push Notifications in Capacitor

When to Use

TRIGGER when:

• Adding remote push (FCM / APNs) to a Capacitor app
• registration / registrationError never fire, or the token works on one platform only
• iOS token is a 64-hex APNs token but the backend expects an FCM token
• Notifications arrive in background but not in foreground (or vice versa)
• Android 13+ shows no prompt and nothing is delivered
• Upgrading to Capacitor 8.5 (UIScene) or 9 (alert presentation option removed)

Do not use:

• Opening the app from https:// / myapp:// links: capacitor-deep-linking
• Moving AppDelegate code to SceneDelegate: capacitor-uiscene-migration
• Device log capture: ios-android-logs
• Choosing other native plugins: capacitor-plugins

Choose the plugin first (ask the user if unclear)

Need	Plugin
Official plugin; APNs token on iOS, FCM token on Android	@capacitor/push-notifications
FCM token on both platforms, topics, Firebase-first backend	@capgo/capacitor-firebase-messaging
Capgo-managed delivery (dashboard campaigns, badges, silent live-update checks, no own push server)	@capgo/capacitor-notifications
Local notifications only, rich layouts	@capgo/capacitor-rich-notifications or @capacitor/local-notifications

The rest of this file covers @capacitor/push-notifications. For Capgo plugins follow https://capgo.app/docs/plugins/firebase-messaging/ or https://capgo.app/docs/plugins/notifications/getting-started/.

Workflow

1. Inspect: package.json versions (@capacitor/core, @capacitor/push-notifications), capacitor.config.* plugins.PushNotifications, ios/App/App/AppDelegate.swift, ios/App/App/*.entitlements, android/app/google-services.json, android/variables.gradle, AndroidManifest.xml.
2. Install: npm install @capacitor/push-notifications && npx cap sync.
3. iOS: capability + APNs key + AppDelegate forwarding. Details: references/ios-setup.md.
4. Android: google-services.json, channel, icon, permission. Details: references/android-setup.md.
5. JS: listeners first, then permission, then register() (below).
6. Backend: send a test message. Payload shapes: references/sending.md.
7. Verify with the checklist below on physical devices.

Only load a reference when its topic is in play.

JS registration (order matters)

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

export async function initPush() {
  // 1. Listeners before register(), or the first token is missed
  await PushNotifications.addListener('registration', ({ value }) => sendTokenToServer(value));
  await PushNotifications.addListener('registrationError', (err) => console.error('push reg', err.error));
  await PushNotifications.addListener('pushNotificationReceived', (n) => {
    // foreground only (and Android data-only while app is alive)
  });
  await PushNotifications.addListener('pushNotificationActionPerformed', ({ notification, actionId }) => {
    routeFromNotification(notification.data); // tap handling
  });

  // 2. Permission (required on iOS and Android 13+ / targetSdk 33+)
  let perm = await PushNotifications.checkPermissions();
  if (perm.receive === 'prompt' || perm.receive === 'prompt-with-rationale') {
    perm = await PushNotifications.requestPermissions();
  }
  if (perm.receive !== 'granted') return; // explain + link to settings, do not loop prompts

  // 3. Register
  await PushNotifications.register();
}

Traps:

• Call initPush() at bootstrap so pushNotificationActionPerformed from a cold-start tap is captured.
• Tokens rotate. Send every registration value to the server and upsert by user + device.
• On iOS the plugin reports the raw APNs token unless AppDelegate swaps in the FCM token (see ios-setup). Sending an APNs token to FCM fails with messaging/invalid-registration-token.
• Ask permission after a user action that explains the value; iOS shows the system prompt only once.

Foreground presentation

// capacitor.config.ts
plugins: {
  PushNotifications: {
    presentationOptions: ['badge', 'sound', 'banner', 'list'],
  },
},

• banner + list replace the deprecated iOS alert. Capacitor 9 removes alert on iOS; replace it when upgrading. badge is iOS only.
• Empty array = nothing shown in foreground; handle pushNotificationReceived yourself.

Capacitor version notes

Version	Change
7	firebaseMessagingVersion default 24.1.0
8	firebaseMessagingVersion default 25.0.1
8.5	UIScene lifecycle. Remote-notification callbacks (didRegisterForRemoteNotificationsWithDeviceToken, didFailToRegister...) stay in AppDelegate and keep working. Do not move them to SceneDelegate. Tap routing that used AppDelegate application(_:open:) must move (see capacitor-deep-linking).
9	iOS alert presentation option removed; iOS 16 min; @main replaces @UIApplicationMain; google-services Gradle plugin 4.5.0

Verification

1. iOS: codesign -d --entitlements :- path/to/App.app | grep aps-environment shows development (debug) or production (TestFlight/App Store).
2. Android: adb shell dumpsys package com.example.app | grep POST_NOTIFICATIONS shows granted=true after accepting the prompt.
3. App logs a registration token on a real device (iOS Simulator on Apple silicon can receive pushes via xcrun simctl push, but test real APNs on device).
4. Send a test from Firebase Console (Messaging -> "Send test message") or your backend to that token.
5. Check all three states: foreground (presentation + pushNotificationReceived), background (system tray), killed (tap -> pushNotificationActionPerformed routes correctly).
6. iOS simulator smoke test without a server:

cat > /tmp/push.apns <<'EOF'
{ "Simulator Target Bundle": "com.example.app", "aps": { "alert": { "title": "Test", "body": "Hello" } }, "route": "/inbox" }
EOF
xcrun simctl push booted com.example.app /tmp/push.apns

(aps.alert in the APNs payload is the message content and is unaffected by the presentationOptions change.)

Error Handling

Error / symptom	Cause	Fix
no valid "aps-environment" entitlement string found for application	Push Notifications capability missing or profile not regenerated	Add capability in Xcode, re-sign, rebuild
registration never fires on iOS, no error	AppDelegate does not post .capacitorDidRegisterForRemoteNotifications	Add forwarding methods to AppDelegate
Default FirebaseApp is not initialized in this process (Android)	google-services.json missing/empty, so google-services plugin was not applied (google-services.json not found, google-services plugin not applied. Push Notifications won't work)	Put file in android/app/, rebuild
messaging/registration-token-not-registered	Token stale (app reinstalled / data cleared)	Delete token server-side; rely on next registration
messaging/invalid-registration-token / BadDeviceToken	APNs token sent to FCM, or sandbox token sent to production APNs	Use FCM token on iOS (ios-setup) or match APNs environment
messaging/third-party-auth-error	APNs key not uploaded to Firebase, wrong Key ID / Team ID	Upload .p8 under Firebase Project Settings -> Cloud Messaging
Android 13+: nothing shown, no prompt	requestPermissions() never called	Call it; manifest permission is added by the plugin
Android shows white square icon	No monochrome notification icon	Set default_notification_icon meta-data
Android notification silent / wrong importance	Channel created with low importance (importance is immutable after creation)	Create a new channel id; delete the old one
Data-only message ignored when app killed (Android)	Plugin only delivers while app process lives	Native FirebaseMessagingService (android-setup)
iOS silent / background push not delivered to JS	Plugin does not support iOS silent push	Native handling, or @capgo/capacitor-notifications silent update checks
Duplicate class errors with Firebase after Capacitor 9	Old core-ktx / Kotlin stdlib pins	See capacitor-app-upgrade-v8-to-v9

Resources

• Plugin API: https://capacitorjs.com/docs/apis/push-notifications
• Firebase guide: https://capacitorjs.com/docs/guides/push-notifications-firebase
• Updating to 9.0: https://capacitorjs.com/docs/updating/9-0
• Capgo Firebase Messaging: https://capgo.app/docs/plugins/firebase-messaging/
• Capgo Notifications: https://capgo.app/docs/plugins/notifications/