🔗 Nexus

← Volver a notas
7 KB 27/09/2026 19:55
🔗

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 a wiki/manuales/publicar-app-movil-capacitor.md.


0. Conceptos clave (para no confundir)

¿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

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/):

  1. Habilitar fcm.googleapis.com (serviceusage).
  2. Crear la service account fcm-sender@<proyecto>.iam.gserviceaccount.com.
  3. Darle el rol roles/firebasecloudmessaging.admin.
  4. 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();

4. Backend: guardar dispositivos y enviar (FCM HTTP v1)

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
);

5. Probar

  1. Instalar el APK en el celular → aceptar "Activar notificaciones" → el token queda en app_devices.
  2. Verificar: SELECT * FROM app_devices;
  3. Enviar: POST /api/notify/client con el client_id → respuesta {app_sent: 1}.
  4. 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)

  1. Registrar la app iOS en el mismo proyecto Firebase (bundle id).
  2. GoogleService-Info.plist → mobile/ios/App/App/.
  3. APNs Auth Key (.p8): developer.apple.com → Keys → "+" → Apple Push Notifications service (APNs) → Key ID + Team ID → subir a Firebase Console → Cloud Messaging.
  4. Capability Push Notifications en el App ID y en Xcode.
  5. El mismo fcm.js sirve (el payload ya incluye el bloque apns).

8. Checklist reusable


Caso de referencia: wiki/proyectos/hoseg-cash-app-movil.md (Hoseg Rewards · proyecto Firebase hoseg-rewards).