workspace/projects/gamilit/apps/frontend/FIREBASE_SETUP.md

Firebase Cloud Messaging Setup

Instalación

Para habilitar las notificaciones push con Firebase, sigue estos pasos:

1. Instalar dependencias de Firebase

cd apps/frontend
npm install firebase

2. Configurar variables de entorno

Copia las variables de Firebase del archivo .env.example a tu archivo .env:

# Firebase Configuration for Push Notifications
VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id
VITE_FIREBASE_VAPID_KEY=your-vapid-key

3. Obtener credenciales de Firebase

1. Ve a Firebase Console
2. Crea un nuevo proyecto o selecciona uno existente
3. Ve a Project Settings > General
4. En la sección Your apps, haz clic en Web app (icono </>)
5. Registra tu app y copia las credenciales del firebaseConfig

4. Obtener VAPID key

1. En Firebase Console, ve a Project Settings > Cloud Messaging
2. En la sección Web Push certificates, genera un nuevo certificado
3. Copia la Key pair (VAPID key)
4. Pégala en VITE_FIREBASE_VAPID_KEY

5. Actualizar Service Worker

Edita el archivo public/firebase-messaging-sw.js y reemplaza el firebaseConfig vacío con tus credenciales:

const firebaseConfig = {
  apiKey: 'your-api-key',
  authDomain: 'your-project.firebaseapp.com',
  projectId: 'your-project-id',
  storageBucket: 'your-project.appspot.com',
  messagingSenderId: 'your-sender-id',
  appId: 'your-app-id',
};

Nota: En un entorno de producción, estas credenciales deben inyectarse en tiempo de build, no hardcodeadas.

6. Probar localmente

1. Inicia el servidor de desarrollo:

   npm run dev
   

2. Ve a Configuración > Dispositivos en el portal de estudiantes

3. Haz clic en Activar Notificaciones Push

4. Acepta los permisos de notificación en tu navegador

5. Deberías ver tu dispositivo registrado en la lista

Arquitectura

Archivos creados

• src/config/firebase.ts: Configuración y funciones de Firebase
• src/features/notifications/hooks/usePushNotifications.ts: Hook para gestión de push
• public/firebase-messaging-sw.js: Service Worker para background notifications

Flujo de registro

1. Usuario hace clic en "Activar Notificaciones Push"
2. usePushNotifications solicita permiso al navegador
3. Si se concede, obtiene el FCM token de Firebase
4. El hook llama a notificationsStore.registerDevice() con el token
5. El backend guarda el token en la tabla user_devices
6. El usuario recibe confirmación de registro exitoso

Flujo de notificaciones

Foreground (app abierta):

1. Firebase recibe mensaje push
2. onForegroundMessage en el hook captura el mensaje
3. Se muestra un toast con react-hot-toast
4. Usuario puede hacer clic para navegar

Background (app cerrada):

1. Service Worker recibe el mensaje
2. onBackgroundMessage muestra notificación nativa del navegador
3. Usuario hace clic en notificación
4. App se abre/enfoca y navega a la URL especificada

Testing

Test manual

1. Usa la consola de Firebase Cloud Messaging para enviar un test message
2. En Compose notification, selecciona tu app web
3. Envía la notificación
4. Deberías recibirla en tu navegador

Test desde backend

El backend puede enviar notificaciones usando el endpoint:

POST /api/notifications/send-push
{
  "userId": "uuid",
  "title": "Test",
  "body": "This is a test notification",
  "data": {
    "action_url": "/achievements"
  }
}

Troubleshooting

"Push notifications no están configuradas"

• Verifica que todas las variables de entorno estén configuradas
• Revisa la consola del navegador para mensajes de error

"Tu navegador no soporta notificaciones push"

• Usa un navegador compatible (Chrome, Firefox, Edge)
• Asegúrate de estar en HTTPS (localhost está exento)

"Permiso de notificaciones denegado"

• Ve a la configuración del navegador
• Busca las notificaciones del sitio
• Cambia el permiso de "Bloqueado" a "Permitir"

Service Worker no se registra

• Verifica que firebase-messaging-sw.js esté en public/
• El archivo debe servirse desde la raíz (/firebase-messaging-sw.js)
• Revisa la consola del navegador para errores de Service Worker

Seguridad

Variables de entorno

• NUNCA commitees archivos .env con credenciales reales
• Usa secretos de CI/CD para variables de producción
• El archivo .env.example debe tener valores vacíos

VAPID key

• Es pública y puede exponerse en el frontend
• Se usa para identificar tu servidor ante Firebase
• No confundir con el Server Key (privado, solo backend)

Device tokens

• Son sensibles y deben protegerse
• Se almacenan hasheados en la base de datos
• Se enmascaran en la API response (primeros 20 caracteres)

Próximos pasos

• Configurar Firebase en el servidor de producción
• Implementar notificaciones desde backend (NestJS + FCM Admin SDK)
• Agregar preferencias de notificación por tipo
• Implementar batching de notificaciones
• Agregar analytics de engagement de notificaciones

Referencias

• Firebase Cloud Messaging Web
• Service Workers API
• Notifications API