Comienza a usar Crashlytics para la Web

Seleccionar plataforma:

iOS+ Android NDK de Android Web Flutter Unity

Versión preliminar: Crashlytics para apps web es una versión preliminar. Las versiones preliminares no están sujetas a ningún ANS ni a ninguna política de baja, y podrían cambiar de manera tal que dejen de ser compatibles con versiones anteriores.

En esta guía, se describe cómo comenzar a usar Firebase Crashlytics en tu app web.

Después de configurar el SDK de Firebase Crashlytics en tu app, puedes obtener informes de fallas completos en Firebase console. Con Crashlytics para apps web, obtienes informes de errores.

Importante: La compatibilidad de Crashlytics con las apps web se lanzará en los próximos días. Si aún no ves la experiencia en la consola de Firebase, vuelve a consultar pronto.

Antes de comenzar

La configuración de Crashlytics requiere realizar tareas en Firebase console y en tu IDE (por ejemplo, agregar la configuración de Firebase de tu app y el SDK de Crashlytics). Para finalizar la configuración, deberás forzar una falla de prueba para enviar el primer informe de fallas a Firebase.

Para configurar Crashlytics de forma manual en tu app web, asegúrate de haber completado los siguientes requisitos previos:

• Crea un proyecto y una app de Firebase si aún no tienes uno. Si aún no lo has hecho, agrega Firebase a tu proyecto de JavaScript.

• Asegúrate de que tu cuenta tenga permisos de propietario en tu proyecto. Esto es necesario para habilitar las APIs y los roles de IAM necesarios.

• Asegúrate de que tu proyecto de Firebase tenga el plan de precios Blaze de pago por uso. Crashlytics para la Web usa Cloud Logging para el almacenamiento de telemetría y Cloud Storage para el almacenamiento de mapas de origen, que son productos pagados con un nivel sin costo. Obtén más información sobre los precios de Logging y los precios de Cloud Storage.

Paso 1: Habilita Crashlytics para tu app web

Crashlytics para la Web usa Cloud Logging, Error Reporting y Cloud Storage, por lo que debes habilitar estas APIs y configurar los permisos para tu proyecto. Puedes habilitar Crashlytics para tu app web con la consola de Firebase o la CLI de Firebase.

Usa Firebase console

1. En la consola de Firebase, ve a DevOps y participación > panel de Crashlytics.

2. Selecciona tu app web en el selector desplegable que se encuentra en la parte superior de la página.

3. Haz clic en Configurar Crashlytics y sigue las instrucciones en pantalla.

Usa la CLI de Firebase

Importante: Si bien la compatibilidad de Crashlytics con las apps web se lanzará en los próximos días, te recomendamos que uses la consola de Firebase para la configuración. Si usas la CLI de Firebase en este momento para configurar Crashlytics, es posible que no puedas ver tus fallas en el panel de Crashlytics hasta más adelante esta semana.

Si prefieres configurar tu proyecto desde la terminal o con un agente de programación de IA, puedes usar la CLI de Firebase:

1. Asegúrate de tener instalada la CLI de Firebase v15.35.0 o una posterior y de que te autenticaste (firebase login). Obtén información para instalar o actualizar la CLI de Firebase.

2. Ejecuta el siguiente comando para configurar Crashlytics en tu app web:

   firebase crashlytics:setup \
     --app FIREBASE_APP_ID \
     --project PROJECT_ID
   

   Este comando realiza los siguientes pasos de configuración:

   • Verifica que tu proyecto tenga el plan de precios Blaze de pago por uso y te solicita que lo actualices si es necesario.

   • Habilita las APIs de Crashlytics y telemetría necesarias (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com y clienttelemetry.googleapis.com).

   • Si la clave de API de tu app web tiene restricciones de API, agrega clienttelemetry.googleapis.com a sus APIs permitidas.

   • Establece la configuración de telemetría de Crashlytics para tu app web.

   • Cuando se ejecuta de forma interactiva, te solicita que habilites de forma opcional las alertas por correo electrónico para los problemas nuevos y recurrentes.

Paso 2: Agrega y, luego, inicializa el SDK en tu app

1. Instala el SDK de Crashlytics:

   npm install firebase
   

2. Inicializa tu instancia de FirebaseApp:

   Crea un archivo de utilidad de configuración central para usar la inicialización de singleton. Para encontrar los valores de configuración de tu app de Firebase, ve a la página Configuración del proyecto > General en la consola de Firebase, ve a la tarjeta Tus apps y selecciona tu app web.

   // src/lib/firebase.ts
   import { initializeApp, getApps, getApp } from '@firebase/app';
   
   const firebaseConfig = {
     apiKey: "API_KEY",
     authDomain: "AUTH_DOMAIN",
     projectId: "PROJECT_ID",
     storageBucket: "STORAGE_BUCKET",
     messagingSenderId: "MESSAGING_SENDER_ID",
     appId: "FIREBASE_APP_ID"
   };
   
   // Guarantee singleton initialization across renders or module refreshes
   export const app = getApps().length === 0
     ? initializeApp(firebaseConfig)
     : getApp();
   

Paso 3: Configura la captura automática de errores para tu framework

Tanto los receptores automáticos de errores del framework como los seguimientos manuales usan tu instancia compartida de FirebaseApp. Selecciona tu framework para configurar la captura automática de errores:

Angular

Integra el entorno de ejecución de captura de errores global de Angular y el seguimiento automático de rutas agregando provideCrashlytics(() => app) a los proveedores de tu app en src/app/app.config.ts:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app)
  ]
};

Nota: provideCrashlytics registra un ErrorHandler personalizado para hacer un seguimiento de las fallas de zona no detectadas (Zone.js) y usa instancias internas de Router para compilar rutas dinámicas (como /dashboard/user/:id) en lugar de registrar URLs literales, lo que mantiene la telemetría libre de información de identificación personal.

Next.js

Next.js 15.3 o versiones posteriores (recomendado): Instrumentación del cliente (instrumentation-client.ts)

Next.js 15.3 y versiones posteriores incluyen instrumentación nativa del cliente a través de instrumentation-client.ts (o instrumentation-client.js). Next.js ejecuta este archivo en el navegador antes de que comience la hidratación de React.

Crea src/instrumentation-client.ts (o instrumentation-client.ts en la raíz del proyecto si no usas un directorio src/) y, luego, inicializa Crashlytics:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app);

Este único archivo inicializa Crashlytics antes de la hidratación de React y registra automáticamente los objetos de escucha de errores globales (error y unhandledrejection) sin modificaciones en src/app/layout.tsx ni en ningún componente de React.

Next.js < 15.3: Del cliente (diseño de App Router)

Para las versiones de Next.js anteriores a la 15.3, layout.tsx es un componente de servidor de forma predeterminada. Debido a que FirebaseApp no se puede serializar, une <FirebaseCrashlytics> (desde @firebase/crashlytics/react para inicializar Crashlytics y capturar errores no detectados) en un componente de cliente (como src/components/CrashlyticsProvider.tsx) marcado con la directiva 'use client':

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics firebaseApp={app} />
      {children}
    </>
  );
}

Luego, une tu diseño raíz con <CrashlyticsProvider>:

// src/app/layout.tsx
import React from 'react';
import { CrashlyticsProvider } from '../components/CrashlyticsProvider';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <CrashlyticsProvider>
          {children}
        </CrashlyticsProvider>
      </body>
    </html>
  );
}

React (sin React Router)

Une el componente raíz de tu app (por lo general, src/App.tsx o src/main.tsx) con el componente de límite de error <FirebaseCrashlytics>. Esto actúa como el receptor global, que controla los rechazos y las excepciones no controlados del navegador y la IU de React. Une todas las jerarquías de componentes secundarios y captura automáticamente las excepciones no detectadas o los errores de enrutamiento:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

export default function App({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics firebaseApp={app}>
      {children}
    </FirebaseCrashlytics>
  );
}

React Router (v6+)

Si usas React Router v6 o una versión posterior, reemplaza el contenedor <Routes> de React Router por <CrashlyticsRoutes>. Esto asigna automáticamente los límites de error en las rutas y hace un seguimiento de los errores con nombres de rutas con plantilla, como /profile/:userId:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes firebaseApp={app}>
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

Si tu app usa TanStack Router, inicializa Crashlytics con getCrashlytics(app) y adjunta el registro de errores predeterminado directamente dentro de la configuración de la instancia del router (defaultOnCatch):

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app);

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

Nota: Cuando se llama a getCrashlytics(app), se registran automáticamente objetos de escucha globales para errores de ventana no detectados y rechazos de promesas no controlados, mientras que defaultOnCatch captura los errores detectados durante el enrutamiento y la renderización de componentes dentro de TanStack Router.

(Opcional) Paso 4: Configura el control de versiones de la app

Se recomienda agregar una cadena de versión clara a las compilaciones de tu app web para que puedas aislar las regresiones en implementaciones específicas. Pasa appVersion en CrashlyticsOptions cuando inicialices el SDK de Crashlytics para tu framework (con una cadena de versión o una variable de entorno de tiempo de compilación, como process.env.NEXT_PUBLIC_APP_VERSION o import.meta.env.VITE_APP_VERSION):

Angular

Pasa un objeto CrashlyticsOptions con appVersion como segundo argumento a provideCrashlytics en src/app/app.config.ts:

// src/app/app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideCrashlytics } from '@firebase/crashlytics/angular';
import { app } from '../lib/firebase'; // Shared initialization script
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideCrashlytics(() => app, {
      appVersion: 'APP_VERSION'
    })
  ]
};

Next.js

Next.js 15.3 o versiones posteriores (recomendado): Instrumentación del cliente (instrumentation-client.ts)

Pasa un objeto CrashlyticsOptions con appVersion como segundo argumento a getCrashlytics en src/instrumentation-client.ts:

// src/instrumentation-client.ts
import { getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

Next.js < 15.3: Del cliente (diseño de App Router)

Pasa crashlyticsOptions con appVersion a <FirebaseCrashlytics> en src/components/CrashlyticsProvider.tsx:

// src/components/CrashlyticsProvider.tsx
'use client';

import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from '../lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export function CrashlyticsProvider({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <FirebaseCrashlytics
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      />
      {children}
    </>
  );
}

React (sin React Router)

Pasa crashlyticsOptions con appVersion a <FirebaseCrashlytics> en src/App.tsx:

// src/App.tsx
import React from 'react';
import { FirebaseCrashlytics } from '@firebase/crashlytics/react';
import { app } from './lib/firebase'; // Shared initialization script

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App({
  children,
}: {
  children?: React.ReactNode;
}) {
  return (
    <FirebaseCrashlytics
      firebaseApp={app}
      crashlyticsOptions={crashlyticsOptions}
    >
      {children}
    </FirebaseCrashlytics>
  );
}

React Router (v6+)

Pasa crashlyticsOptions con appVersion a <CrashlyticsRoutes> en src/App.tsx:

// src/App.tsx
import React from 'react';
import { BrowserRouter, Route } from 'react-router-dom';
import { CrashlyticsRoutes } from '@firebase/crashlytics/react-router';
import { app } from './lib/firebase'; // Shared initialization script
import Home from './pages/Home';
import Profile from './pages/Profile';
import Product from './pages/Product';

const crashlyticsOptions = {
  appVersion: 'APP_VERSION'
};

export default function App() {
  return (
    <BrowserRouter>
      <CrashlyticsRoutes
        firebaseApp={app}
        crashlyticsOptions={crashlyticsOptions}
      >
        <Route path="/" element={<Home />} />
        <Route path="/profile/:userId" element={<Profile />} />
        <Route path="/product/:productId/details" element={<Product />} />
      </CrashlyticsRoutes>
    </BrowserRouter>
  );
}

TanStack Router

Pasa un objeto CrashlyticsOptions con appVersion como segundo argumento a getCrashlytics:

import { recordError, getCrashlytics } from '@firebase/crashlytics';
import { app } from './lib/firebase'; // Shared initialization script

import { createRouter } from '@tanstack/react-router';
import { routeTree } from './routeTree.gen';

const crashlytics = getCrashlytics(app, {
  appVersion: 'APP_VERSION'
});

const router = createRouter({
  routeTree,
  defaultOnCatch: (error, errorInfo) => {
    recordError(crashlytics, error, errorInfo);
  },
});

Paso 5: Fuerza una falla de prueba

Para finalizar la configuración de Crashlytics y ver los datos iniciales en el panel de Crashlytics de Firebase console, debes forzar una falla de prueba.

1. Agrega código a tu app para forzar una falla de prueba.

   Agrega un botón de prueba o un activador de ruta a tu app de React, Next.js o Angular que arroje un error de tiempo de ejecución cuando se haga clic en él:

   // Trigger an unhandled exception on button click or route load
   function handleTestCrash() {
     throw new Error("Crashlytics Web SDK Test Unhandled Error!");
   }
   

   Si configuraste la captura automática de errores con <FirebaseCrashlytics> (React o Next.js), provideCrashlytics (Angular) o <CrashlyticsRoutes> (React Router), arrojar este error captura automáticamente la excepción y la programa para subirla.

2. Compila y ejecuta tu app y, luego, activa el error de prueba para que la app envíe su primer informe de fallas a Firebase.

3. En la consola de Firebase, ve al panel DevOps & Engagement > Crashlytics para verificar el informe de fallas de prueba:

   1. Selecciona tu app web en el selector desplegable que se encuentra en la parte superior de la página.

   2. Actualiza la página. La excepción de prueba debería aparecer en la tabla Problemas en unos minutos.

Si actualizaste la consola y sigues sin poder ver la falla de prueba después de cinco a diez minutos, consulta Soluciona problemas de configuración.

Ahora Crashlytics supervisa tu app web para detectar errores. Visita el panel de Crashlytics para ver y analizar todos los informes y estadísticas.

Próximos pasos

• Obtén informes de fallas legibles: Configura la carga automática de mapas de origen (.js.map) para que los seguimientos de pila de producción muestren los nombres de archivo y los números de línea originales.
• Personaliza los informes de fallas: Obtén información para informar excepciones controladas, agregar claves personalizadas, forzar el vaciado de los registros de telemetría y configurar el muestreo.