Playbook — Notificaciones push nativas (Firebase Cloud Messaging) para una app Capacitor
Creado: 2026-09-27 · Caso base: Hoseg Rewards (app del wallet, Capacitor 8 · Android + iOS)
Reutilizable para cualquier app nuestra. Complementa awiki/manuales/publicar-app-movil-capacitor.md.
0. Conceptos clave (para no confundir)
- Firebase = la "central de envíos". Dentro de un proyecto se registran apps (Android/iOS/Web), cada una con su config.
- Las notificaciones NO se envían a una app: se envían a un token de dispositivo. Cada instalación genera su token propio → imposible que se cruce entre apps (salvo usar topics).
- Web Push (navegador,
web-push/VAPID) y push nativo (FCM/APNs) son canales distintos. En una app Capacitor el navegador no recibe web push → hace falta FCM/APNs. - Android: FCM. iOS: FCM → APNs (necesita una APNs key .p8 subida a Firebase + el Team ID).
¿Proyecto Firebase compartido o propio?
- Compartido: rápido, pero cualquiera con acceso al proyecto/service account puede enviar a todas las apps y las métricas se mezclan.
- Propio (recomendado para productos distintos / SaaS multi-negocio): aislamiento total de credenciales, permisos, cuotas y consola.
1. Crear el proyecto Firebase y registrar la app
# Login (una vez; autoriza Daniel con su Google)
npx --yes firebase-tools@latest login --no-localhost
# Crear proyecto
npx --yes firebase-tools@latest projects:create <proyecto> --display-name "Hoseg Rewards"
# Registrar la app Android (package = applicationId)
npx --yes firebase-tools@latest apps:create ANDROID "Hoseg Rewards" \
--package-name com.hoseg.rewards --project <proyecto>
# Descargar la config → se copia a mobile/android/app/google-services.json
npx --yes firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <proyecto> \
--out proyectos/<app>/mobile/android/app/google-services.json
- iOS:
firebase apps:create IOS "Hoseg Rewards" --bundle-id com.hoseg.rewardsy descargarGoogleService-Info.plist. - El plugin google-services se aplica solo si existe
google-services.json(el template de Capacitor ya trae el classpath enandroid/build.gradle).
2. Service account para enviar desde el backend
El backend firma un JWT (RS256) con la service account y pide un access token a Google. Se crea con la API de IAM usando el token del CLI (script setup-fcm-sa.js, ver credentials/firebase-rewards/):
- Habilitar
fcm.googleapis.com(serviceusage). - Crear la service account
fcm-sender@<proyecto>.iam.gserviceaccount.com. - Darle el rol
roles/firebasecloudmessaging.admin. - Crear una clave JSON (
TYPE_GOOGLE_CREDENTIALS_FILE) → guardarla con permisos 600.
Ubicación en el servidor: el contenedor debe poder leerla. Como el contenedor solo monta ./data y ./public:
scp service-account-fcm.json <host>:/tmp/sa.json
ssh <host> 'docker cp /tmp/sa.json <contenedor>:/app/data/fcm-service-account.json'
(⚠️ Nunca dentro de public/ — se serviría públicamente.) Alternativa: env FCM_SERVICE_ACCOUNT_JSON.
3. App: plugin + registro del token
cd proyectos/<app> && npm i @capacitor/push-notifications@^8 && npx cap sync android
En la pantalla de arranque (antes de entrar al contenido):
const PN = window.Capacitor?.Plugins?.PushNotifications;
PN.addListener('registration', (t) => {
fetch(API + '/api/app/device', { method:'POST', headers:{'Content-Type':'application/json'},
body: JSON.stringify({ token: walletToken, fcm_token: t.value, platform: Capacitor.getPlatform() }) });
});
let perm = await PN.checkPermissions();
if (perm.receive !== 'granted') perm = await PN.requestPermissions();
if (perm.receive === 'granted') await PN.register();
- Pedir el permiso con un botón ("Activar notificaciones") — mejor UX y evita bloqueos del sistema.
- En Android 13+ el permiso
POST_NOTIFICATIONSlo gestiona el plugin.
4. Backend: guardar dispositivos y enviar (FCM HTTP v1)
- Tabla:
CREATE TABLE IF NOT EXISTS app_devices (
id INTEGER PRIMARY KEY AUTOINCREMENT,
client_id INTEGER NOT NULL,
token TEXT UNIQUE NOT NULL, -- token FCM
platform TEXT DEFAULT 'android',
active INTEGER DEFAULT 1,
created_at TEXT DEFAULT (datetime('now','localtime')),
last_seen TEXT
);
- Endpoint público
POST /api/app/device{ token (identidad), fcm_token, platform }→ upsert. - CORS: agregar los orígenes de Capacitor (
capacitor://localhost,http://localhost,https://localhost) o las llamadas desde la app fallan. - Envío:
server/fcm.js(enviarTokens(tokens, {title, body, url, data}, onInvalid)) — sin dependencias: JWT RS256 concrypto+POST https://fcm.googleapis.com/v1/projects/<proyecto>/messages:send. - Marcar como inactivo cuando FCM responde
UNREGISTERED/NOT_FOUND/INVALID_ARGUMENT. - Endpoint admin
POST /api/notify/client {client_id|token, title, body}→ envía a ese cliente (app nativa y web push).
5. Probar
- Instalar el APK en el celular → aceptar "Activar notificaciones" → el token queda en
app_devices. - Verificar:
SELECT * FROM app_devices; - Enviar:
POST /api/notify/clientcon elclient_id→ respuesta{app_sent: 1}. - La notificación debe aparecer en la app (no en Chrome).
6. Errores comunes
| Síntoma | Causa | Solución |
|---|---|---|
| Llega a Chrome pero no a la app | Se usó web push (VAPID); la app necesita FCM | Implementar FCM nativo (esto). |
Push no configurado en el backend |
Falta/carpeta equivocada del service account | Copiarla al volumen del contenedor (/app/data/…) o usar env. |
FCM auth 403/401 |
Rol o proyecto equivocados | Rol firebasecloudmessaging.admin en ese proyecto. |
El dispositivo no aparece en app_devices |
CORS bloqueó el POST, o no se aceptó el permiso | Agregar orígenes Capacitor a CORS; pedir permiso y register(). |
MismatchSenderId |
El token es de otro proyecto Firebase | Usar las credenciales del proyecto correcto (por eso conviene un proyecto por producto). |
| iOS no recibe | Falta la APNs key .p8 en Firebase o el capability Push | Subir .p8 (Keys → APNs) + Team ID; activar Push Notifications en el App ID. |
7. iOS (pendiente por app)
- Registrar la app iOS en el mismo proyecto Firebase (bundle id).
GoogleService-Info.plist→mobile/ios/App/App/.- APNs Auth Key (.p8): developer.apple.com → Keys → "+" → Apple Push Notifications service (APNs) → Key ID + Team ID → subir a Firebase Console → Cloud Messaging.
- Capability Push Notifications en el App ID y en Xcode.
- El mismo
fcm.jssirve (el payload ya incluye el bloqueapns).
8. Checklist reusable
- [ ] Proyecto Firebase creado (propio o compartido según el producto)
- [ ] Apps Android/iOS registradas + configs descargadas
- [ ] Service account con rol FCM admin + clave JSON en el contenedor (permisos 600)
- [ ]
google-services.jsonenandroid/app/ycap sync - [ ] Plugin
@capacitor/push-notifications+ pantalla de permiso - [ ] Tabla
app_devices+ endpointPOST /api/app/device - [ ] CORS con los orígenes Capacitor
- [ ]
fcm.js(FCM v1) + endpoint admin para notificar a un cliente - [ ] Prueba real: notificación llega a la app
- [ ] iOS: APNs key .p8 + capability Push
Caso de referencia: wiki/proyectos/hoseg-cash-app-movil.md (Hoseg Rewards · proyecto Firebase hoseg-rewards).