cap-go/capgo-skills/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)

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

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

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/