GUI-DGT-002 Plantilla de Guías para Integración de Firebase

v 2.1

Objetivo

El propósito de esta guía es establecer un procedimiento estandarizado para la integración completa de Firebase en aplicaciones web y backends utilizando TypeScript, React Vite y Node.js. Al seguir estos pasos, los desarrolladores podrán implementar características avanzadas como autenticación con Google y envío de notificaciones push, mejorando así la interactividad y la funcionalidad de las aplicaciones.

Notas introductorias

Firebase proporciona un conjunto de herramientas backend robustas que facilitan la creación y el manejo de aplicaciones web y móviles escalables. Esta guía describe el proceso de configuración de un entorno de Firebase, incluyendo la creación de cuentas, la configuración de proyectos, y la integración con aplicaciones web y servidores usando las mejores prácticas de desarrollo con React y Node.js. También se abordan procedimientos para el manejo de autenticación y notificaciones en tiempo real, crucial para aplicaciones modernas.

Contenido

1. Crear un proyecto en Firebase Console.

Paso 1: Crear una Cuenta de Google

Para usar Firebase, necesitas una cuenta de Google. Si ya tienes una, puedes usar esa; de lo contrario, visita https://accounts.google.com/signup para crear una nueva.

Paso 2: Acceder a Firebase

Visita https://firebase.google.com/ y haz clic en "Ir a la consola" en la esquina superior derecha para acceder a la consola de Firebase.

2. Crear un Proyecto en Firebase

Paso 3: Crear un Nuevo Proyecto

1. En la consola de Firebase, haz clic en "Agregar proyecto".
2. Ingresa un nombre para tu proyecto y haz clic en "Continuar".
3. (Opcional) Desactiva Google Analytics para el proyecto si no deseas usarlo, y haz clic en "Continuar".
4. Selecciona una cuenta de Google Analytics para asociar con el proyecto si decidiste activarlo, o crea una nueva.
5. Haz clic en "Crear proyecto". Esto puede tardar unos minutos.

3. Añadir Firebase a tu Proyecto

Instalar Firebase y Tipos de Firebase para TypeScript

Instala el SDK de Firebase y los tipos de TypeScript para Firebase con pnpm:

pnpm install firebase
pnpm install @types/firebase --save-dev

4. Configurar Firebase para tu Página Web

Paso 4: Registrar tu Aplicación

1. Una vez que el proyecto esté listo, verás la consola de tu proyecto. Haz clic en el icono de la web (</>) para registrar tu aplicación web.
2. Ingresa un alias para tu aplicación y, si lo deseas, marca la casilla para también configurar Firebase Hosting. Luego, haz clic en "Registrar aplicación".

Paso 5: Añadir Firebase a tu Página Web

Firebase te proporcionará un fragmento de código que deberás incluir en tu página web. Este código incluye las claves de configuración de tu proyecto y carga Firebase SDK.

5. Configurar Firebase en TypeScript

Crear un Archivo TypeScript para la Configuración de Firebase

Crea un archivo llamado firebase-config.ts en tu proyecto. Dentro de este archivo, puedes inicializar Firebase usando la configuración específica de tu proyecto que se encuentra en tu consola de Firebase.

typescriptCopy code
// Importar Firebase y los servicios que necesitas
import firebase from 'firebase/app';
import 'firebase/auth';   // Si vas a usar autenticación
import 'firebase/firestore'; // Si vas a usar Firestore

// Configuración de Firebase para tu web
const firebaseConfig = {
  apiKey: "tu-api-key",
  authDomain: "tu-project-id.firebaseapp.com",
  projectId: "tu-project-id",
  storageBucket: "tu-project-id.appspot.com",
  messagingSenderId: "tu-sender-id",
  appId: "tu-app-id"
};

// Inicializar Firebase
firebase.initializeApp(firebaseConfig);

// Exportar instancias de servicios que utilizarás
export const auth = firebase.auth();
export const db = firebase.firestore();

Paso 6: Finalizar la Configuración

1. Sigue las instrucciones adicionales en la consola de Firebase para completar la configuración, como configurar Firebase Hosting si es necesario.
2. Después de agregar el código a tu sitio, verifica que todo funcione correctamente haciendo una prueba de conexión o autenticación.

Configurar Firebase Google OAuth

Parte 1: Configuración del Frontend en React

Instalar Dependencias

Primero, necesitas tener Firebase instalado en tu proyecto de React. Si no lo has hecho aún, puedes añadir Firebase con el siguiente comando:

pnpm install firebase

Configuración de Firebase en React

Utiliza el siguiente archivo para inicializar Firebase en tu aplicación React. Este archivo firebase-config.ts configura el SDK de Firebase con tus credenciales:

Archivo: firebase-config.ts

import { initializeApp } from "firebase/app";
import { getAuth, GoogleAuthProvider } from "firebase/auth";

const firebaseConfig = {
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
  appId: import.meta.env.VITE_FIREBASE_APP_ID,
};

const app = initializeApp(firebaseConfig);
const auth = getAuth(app);
const provider = new GoogleAuthProvider();
provider.setCustomParameters({
  login_hint: "user@example.com",
});

export { app, auth, provider };

Implementar la Autenticación en React

Archivo: Login.tsx

import React from "react";
import { auth, provider } from "./firebase-config";
import { signInWithPopup } from "firebase/auth";

const Login = () => {
  const handleLogin = async () => {
    try {
      const result = await signInWithPopup(auth, provider);
      const credential = GoogleAuthProvider.credentialFromResult(result);
      const token = credential?.accessToken;
      const user = result.user;
      console.log("Usuario autenticado:", user);
      // Puedes guardar el token en el estado global o hacer una llamada al backend
    } catch (error) {
      console.error("Error en la autenticación:", error);
    }
  };

  return <button onClick={handleLogin}>Iniciar sesión con Google</button>;
};

export default Login;

Parte 2: Configuración del Backend en Node con Express

Instalar Firebase Admin

Si no has instalado Firebase Admin, puedes hacerlo con el siguiente comando:

pnpm install firebase-admin

Configuración de Firebase Admin

Utiliza el siguiente archivo para inicializar Firebase Admin en tu aplicación Node.js. Asegúrate de tener el archivo de clave privada como se describió previamente.

Archivo: firebase-admin-config.ts

import * as admin from "firebase-admin";

const privateKey = process.env.FIREBASE_PRIVATE_KEY;
if (!privateKey) {
  throw new Error("INTERNAL_SERVER_ERROR: Firebase private key is not set");
}

admin.initializeApp({
  credential: admin.credential.cert(
    JSON.parse(privateKey) as admin.ServiceAccount
  ),
});

export default admin;

Verificar el Token de Autenticación

Utiliza este middleware en tus rutas de Express para asegurarte de que los usuarios están autenticados.

Archivo: verifyToken.ts

import admin from "./firebase-admin-config";
import { Request, Response, NextFunction } from "express";

export const verifyToken = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  const token = req.headers.authorization?.split("Bearer ")[1];
  if (!token) {
    return res.status(401).send("Access denied. No token provided.");
  }

  admin
    .auth()
    .verifyIdToken(token)
    .then((decodedToken) => {
      req.user = decodedToken;
      next();
    })
    .catch((error) => {
      res.status(400).send("Invalid token.");
    });
};

Configurar Firebase Cloud Messaging

Parte 1: Configuración de FCM en el Backend (Node.js)

Paso 1: Configurar Firebase Admin para FCM

Asegúrate de que Firebase Admin está correctamente inicializado en tu servidor, como se indicó en tus archivos previos. Firebase Admin será utilizado para enviar mensajes push.

Paso 2: Obtener el Token de Dispositivo del Usuario

Para enviar mensajes a un dispositivo específico, necesitas obtener y almacenar el token FCM del dispositivo del usuario. Esto se hace generalmente en el frontend cuando el usuario accede a la aplicación y acepta recibir notificaciones.

Parte 2: Configuración en el Frontend (React)

Paso 3: Solicitar Permiso y Obtener Token FCM

En tu aplicación React, debes solicitar permiso al usuario para enviarle notificaciones y luego obtener el token del dispositivo.

Instala el SDK de Firebase para mensajería:

pnpm install firebase/messaging

Agrega la solicitud de permiso y obtención del token en tu archivo de configuración de Firebase o en un componente dedicado:

Archivo: firebase-messaging.ts

import { initializeApp } from "firebase/app";
import { getMessaging, getToken, onMessage } from "firebase/messaging";

const firebaseConfig = {
  // Tu configuración de Firebase
};

const app = initializeApp(firebaseConfig);
const messaging = getMessaging(app);

export const requestUserPermission = async () => {
  return Notification.requestPermission().then((permission) => {
    if (permission === "granted") {
      console.log("Permission granted");
      return getToken(messaging, { vapidKey: "your_vapid_key_here" });
    } else {
      console.error("Unable to get permission to notify.");
    }
  });
};

export const onMessageListener = () =>
  new Promise((resolve) => {
    onMessage(messaging, (payload) => {
      resolve(payload);
    });
  });

export default messaging;

En este código, debes reemplazar 'your_vapid_key_here' con tu VAPID key de la configuración de FCM en Firebase Console.

Obtención de la Clave VAPID desde Firebase

La clave VAPID se utiliza para autenticar tu servidor de aplicaciones ante los servicios de mensajería web como Firebase Cloud Messaging, y es esencial para enviar notificaciones push a los navegadores de los usuarios.

Paso 1: Acceder a la Configuración de FCM en Firebase

1. Ir a la Consola de Firebase: Abre la Consola de Firebase y selecciona tu proyecto.
2. Navegar a Configuración del Proyecto: Haz clic en el ícono de engranaje al lado de "Project Overview" en el panel lateral izquierdo y selecciona "Project settings".
3. Ir a la Pestaña Cloud Messaging: En las configuraciones del proyecto, encuentra la pestaña "Cloud Messaging".
4. Claves de la API de la Aplicación Web: Aquí deberías ver la sección "Web configuration" o "Configuración web". En esta sección, encontrarás la clave pública, conocida como la clave VAPID, que necesitarás para configurar el cliente de mensajería en tu aplicación web.

Paso 4: Enviar el Token al Backend

Después de obtener el token en el frontend, debes enviarlo al backend y almacenarlo, posiblemente asociado con el usuario específico (esto puede ser a través de una API REST que guardará el token en una base de datos).

Parte 3: Enviar Notificaciones desde el Backend

Paso 5: Crear la Función de Envío de Notificaciones

En el backend, crea una función para enviar notificaciones a los tokens guardados cuando se actualicen ciertos estados.

Archivo: sendNotification.ts

typescriptCopy code
import admin from './firebase-admin-config';

export const sendNotification = async (userTokens: string[], messageBody: string) => {
  const message = {
    notification: {
      title: 'Estado Actualizado',
      body: messageBody,
    },
    tokens: userTokens,
  };

  admin.messaging().sendMulticast(message)
    .then((response) => {
      console.log(`Successfully sent message:`, response);
    })
    .catch((error) => {
      console.log(`Error sending message:`, error);
    });
};

Esta función toma una lista de tokens y un mensaje, y utiliza el método sendMulticast para enviar la notificación a todos los dispositivos correspondientes.

Parte 4: Recibir Notificaciones en el Frontend

Paso 6: Escuchar las Notificaciones en React

Utiliza el listener que configuraste para manejar las notificaciones entrantes:

Componente en React, por ejemplo en App.tsx

import React, { useEffect } from "react";
import { onMessageListener } from "./firebase-messaging";

const App = () => {
  useEffect(() => {
    onMessageListener()
      .then((payload) => {
        console.log("Received foreground message ", payload);
        // Puedes mostrar una notificación en pantalla usando una librería como notistack o similar
      })
      .catch((err) => console.log("failed: ", err));
  }, []);

  return <div>{/* Tu UI aquí */}</div>;
};

export default App;

Control de cambios

Versión	Cambio realizado	Análisis	Autor	Revisor(es)	Fecha de cambio
v 1.0	Creacion de estandar	N/A	Daniel Hurtado	Carlos Salguero	12/04/2024
v 2.0	Ajuste de formato	Se modificó el contenido de la guía de acuerdo a la plantilla porque el documento tenía información no requeridas	Yuna Chung	Ricardo Fernández	24/04/2024
v 2.1	Ajustar formato	Se modificó la numeración de las fases	Damariz Licea Sebastian Flores	Ricardo Rosales	28/04/2024