Erste Schritte mit Crashlytics für das Web

Plattform auswählen:

iOS+ Android Android NDK Web Flutter Unity

Vorschau: Crashlytics für Webanwendungen ist eine Vorabversion. Eine Vorabversion unterliegt weder einem SLA noch einer Richtlinie zur Einstellung von Produkten und Diensten und kann sich in einer Weise ändern, die nicht abwärtskompatibel ist.

In diesem Leitfaden werden die ersten Schritte mit Firebase Crashlytics in Ihrer Webanwendung beschrieben.

Nachdem Sie das Firebase Crashlytics SDK in Ihrer App eingerichtet haben, können Sie in der Firebase Console umfassende Absturzberichte abrufen. Mit Crashlytics für Webanwendungen erhalten Sie Berichte zu Fehlern.

Wichtig: Die Unterstützung von Crashlytics für Web-Apps wird in den nächsten Tagen eingeführt. Wenn Sie die Funktion in der Firebase-Konsole noch nicht sehen, schauen Sie bald wieder vorbei.

Hinweis

Für die Einrichtung von Crashlytics sind Aufgaben sowohl in der Firebase-Konsole als auch in Ihrer IDE erforderlich, z. B. das Hinzufügen der Firebase-Konfiguration Ihrer App und des Crashlytics SDK. Um die Einrichtung abzuschließen, müssen Sie einen Testabsturz erzwingen, damit der erste Absturzbericht an Firebase gesendet wird.

Wenn Sie Crashlytics manuell in Ihrer Webanwendung einrichten möchten, müssen Sie die folgenden Voraussetzungen erfüllen:

• Erstellen Sie ein Firebase-Projekt und eine Firebase-App, falls Sie noch keine haben. Falls noch nicht geschehen, fügen Sie Ihrem JavaScript-Projekt Firebase hinzu.

• Ihr Konto muss die Berechtigung Inhaber für Ihr Projekt haben. Dies ist erforderlich, um die erforderlichen APIs und IAM-Rollen zu aktivieren.

• Achten Sie darauf, dass für Ihr Firebase-Projekt das Blaze-Preismodell (Pay as you go) gilt. Crashlytics für das Web verwendet Cloud Logging für die Telemetriespeicherung und Cloud Storage für die Speicherung von Quellzuordnungen. Dies sind kostenpflichtige Produkte mit einer kostenlosen Stufe. Weitere Informationen zu den Preisen für Logging und den Preisen für Cloud Storage.

Schritt 1: Crashlytics für Ihre Web-App aktivieren

Crashlytics für das Web verwendet Cloud Logging, Error Reporting und Cloud Storage. Sie müssen diese APIs also aktivieren und Berechtigungen für Ihr Projekt konfigurieren. Sie können Crashlytics für Ihre Webanwendung entweder über die Firebase Console oder die Firebase CLI aktivieren.

Verwenden Sie die Firebase Console.

1. Rufen Sie in der Firebase Console DevOps & Engagement > Crashlytics-Dashboard auf.

2. Wählen Sie oben auf der Seite im Drop-down-Menü Ihre Web-App aus.

3. Klicken Sie auf Crashlytics einrichten und folgen Sie der Anleitung auf dem Bildschirm.

Firebase CLI verwenden

Wichtig: Die Unterstützung von Crashlytics für Web-Apps wird in den nächsten Tagen eingeführt. Wir empfehlen jedoch, die Firebase-Konsole für die Einrichtung zu verwenden. Wenn Sie die Firebase-Befehlszeile jetzt verwenden, um Crashlytics einzurichten, können Sie Ihre Abstürze möglicherweise erst später in dieser Woche im Crashlytics-Dashboard sehen.

Wenn Sie Ihr Projekt lieber über das Terminal oder mit einem KI-Codierungs-Agenten konfigurieren möchten, können Sie die Firebase-Befehlszeile verwenden:

1. Sie benötigen die Firebase CLI-Version 15.35.0 oder höher und müssen authentifiziert sein (firebase login). Firebase CLI installieren oder aktualisieren

2. Führen Sie den folgenden Befehl aus, um Crashlytics für Ihre Webanwendung einzurichten:

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

   Mit diesem Befehl werden die folgenden Einrichtungsschritte ausgeführt:

   • Prüft, ob für Ihr Projekt das Blaze-Preismodell (Pay as you go) gilt, und fordert Sie gegebenenfalls zu einem Upgrade auf.

   • Aktiviert die erforderlichen Crashlytics- und Telemetrie-APIs (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com und clienttelemetry.googleapis.com).

   • Wenn der API-Schlüssel Ihrer Webanwendung API-Einschränkungen hat, fügen Sie clienttelemetry.googleapis.com zu den zulässigen APIs hinzu.

   • Konfiguriert die Crashlytics-Telemetrieeinstellungen für Ihre Webanwendung.

   • Wenn Sie den Befehl interaktiv ausführen, werden Sie aufgefordert, optional E‑Mail-Benachrichtigungen für neue und zurückgefallene Probleme zu aktivieren.

Schritt 2: SDK in Ihrer App hinzufügen und initialisieren

1. Installieren Sie das Crashlytics SDK:

   npm install firebase
   

2. Initialisieren Sie Ihre FirebaseApp-Instanz:

   Erstellen Sie eine zentrale Konfigurationsdatei, um die Singleton-Initialisierung zu verwenden. Die Konfigurationswerte Ihrer Firebase-App finden Sie in der Firebase-Konsole auf der Seite Projekteinstellungen > Allgemein. Gehen Sie dort zur Karte Meine Apps und wählen Sie Ihre Web-App aus.

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

Schritt 3: Automatische Fehlererfassung für Ihr Framework konfigurieren

Sowohl automatische Framework-Fehlerempfänger als auch manuelle Tracker verwenden Ihre freigegebene FirebaseApp-Instanz. Wählen Sie Ihr Framework aus, um die automatische Fehlererfassung zu konfigurieren:

Angular

Fügen Sie provideCrashlytics(() => app) zu den Anbietern Ihrer Anwendung in src/app/app.config.ts hinzu, um die globale Laufzeit zur Fehlererfassung und das automatische Routen-Tracking von Angular zu integrieren:

// 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)
  ]
};

Hinweis: provideCrashlytics registriert einen benutzerdefinierten ErrorHandler, um nicht abgefangene Zonenabstürze (Zone.js) zu verfolgen, und verwendet interne Router-Instanzen, um dynamische Routen (z. B. /dashboard/user/:id) zu erstellen, anstatt literale URLs zu protokollieren. So bleiben die Telemetriedaten frei von personenidentifizierbaren Informationen.

Next.js

Next.js 15.3+ (empfohlen): Client-Instrumentierung (instrumentation-client.ts)

Next.js 15.3+ enthält eine native clientseitige Instrumentierung über instrumentation-client.ts (oder instrumentation-client.js). Next.js führt diese Datei im Browser aus, bevor die React-Hydratation beginnt.

Erstellen Sie src/instrumentation-client.ts (oder instrumentation-client.ts im Stammverzeichnis Ihres Projekts, wenn Sie kein src/-Verzeichnis verwenden) und initialisieren Sie Crashlytics:

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

getCrashlytics(app);

Diese einzelne Datei initialisiert Crashlytics vor der React-Hydratation und registriert automatisch globale Fehler-Listener (error und unhandledrejection), ohne dass Änderungen an src/app/layout.tsx oder einer React-Komponente vorgenommen werden müssen.

Next.js < 15.3: Clientseitig (App Router-Layout)

In Next.js-Versionen vor 15.3 ist layout.tsx standardmäßig eine Serverkomponente. Da FirebaseApp nicht serialisierbar ist, müssen Sie <FirebaseCrashlytics> (aus @firebase/crashlytics/react, um Crashlytics zu initialisieren und nicht abgefangene Fehler zu erfassen) in eine Clientkomponente (z. B. src/components/CrashlyticsProvider.tsx) einbinden, die mit der Anweisung 'use client' gekennzeichnet ist:

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

Umschließen Sie dann Ihr Root-Layout mit <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 (ohne React Router)

Umschließen Sie die Stammkomponente Ihrer App (normalerweise src/App.tsx oder src/main.tsx) mit der Fehlergrenzenkomponente <FirebaseCrashlytics>. Dies fungiert als globaler Empfänger, der nicht behandelte Ablehnungen und Ausnahmen vom Browser und der React-UI verarbeitet. Sie umschließt alle untergeordneten Komponentenhierarchien und erfasst automatisch nicht abgefangene Ausnahmen oder Routingfehler:

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

Wenn Sie React Router v6 oder höher verwenden, ersetzen Sie den <Routes>-Container von React Router durch <CrashlyticsRoutes>. Dadurch werden Fehlergrenzen automatisch über Routen hinweg zugeordnet und Fehler werden mithilfe von Vorlagenpfadnamen wie /profile/:userId verfolgt:

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

Wenn Ihre App TanStack Router verwendet, initialisieren Sie Crashlytics mit getCrashlytics(app) und hängen Sie die Standardfehleraufzeichnung direkt in der Konfiguration Ihrer Routerinstanz (defaultOnCatch) an:

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

Hinweis: Durch den Aufruf von getCrashlytics(app) werden automatisch globale Listener für nicht abgefangene Fensterfehler und nicht verarbeitete Promise-Ablehnungen registriert. defaultOnCatch erfasst Fehler, die während des Routings und des Komponenten-Renderings in TanStack Router abgefangen werden.

(Optional) Schritt 4: Versionsverwaltung für Anwendungen einrichten

Es wird dringend empfohlen, den Builds Ihrer Web-App einen eindeutigen Versionsstring hinzuzufügen, damit Sie Regressionen bestimmten Bereitstellungen zuordnen können. Übergeben Sie appVersion in CrashlyticsOptions, wenn Sie das Crashlytics SDK für Ihr Framework initialisieren (mit einem Release-String oder einer Umgebungsvariable zur Build-Zeit, z. B. process.env.NEXT_PUBLIC_APP_VERSION oder import.meta.env.VITE_APP_VERSION):

Angular

Übergeben Sie ein CrashlyticsOptions-Objekt mit appVersion als zweites Argument an provideCrashlytics in 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+ (empfohlen): Client-Instrumentierung (instrumentation-client.ts)

Übergeben Sie ein CrashlyticsOptions-Objekt mit appVersion als zweites Argument an getCrashlytics in 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: Clientseitig (App Router-Layout)

Übergeben Sie crashlyticsOptions mit appVersion an <FirebaseCrashlytics> in 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 (ohne React Router)

Übergeben Sie crashlyticsOptions mit appVersion an <FirebaseCrashlytics> in 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+)

Übergeben Sie crashlyticsOptions mit appVersion an <CrashlyticsRoutes> in 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

Übergeben Sie ein CrashlyticsOptions-Objekt mit appVersion als zweites Argument an 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);
  },
});

Schritt 5: Testabsturz erzwingen

Wenn Sie die Einrichtung von Crashlytics abschließen und erste Daten im Dashboard Crashlytics der Firebase Console sehen möchten, müssen Sie einen Testabsturz erzwingen.

1. Fügen Sie Ihrer App Code hinzu, mit dem Sie einen Testabsturz erzwingen können.

   Fügen Sie Ihrer React-, Next.js- oder Angular-Anwendung einen Test-Button oder einen Routen-Trigger hinzu, der beim Klicken einen Laufzeitfehler auslöst:

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

   Wenn Sie die automatische Fehlererfassung mit <FirebaseCrashlytics> (React oder Next.js), provideCrashlytics (Angular) oder <CrashlyticsRoutes> (React Router) konfiguriert haben, wird die Ausnahme automatisch erfasst und für den Upload geplant, wenn dieser Fehler ausgelöst wird.

2. Erstellen Sie Ihre App und führen Sie sie aus. Lösen Sie dann den Testfehler aus, damit Ihre App den ersten Absturzbericht an Firebase sendet.

3. Rufen Sie in der Firebase-Konsole das Dashboard DevOps & Engagement > Crashlytics auf, um nach dem Testabsturzbericht zu suchen:

   1. Wählen Sie oben auf der Seite im Drop-down-Menü Ihre Web-App aus.

   2. Aktualisieren Sie die Seite. Die Testausnahme sollte innerhalb weniger Minuten in der Tabelle Probleme angezeigt werden.

Wenn Sie die Console aktualisiert haben und der Testabsturz nach fünf bis zehn Minuten immer noch nicht angezeigt wird, lesen Sie den Abschnitt Fehlerbehebung bei der Einrichtung.

Crashlytics überwacht Ihre Webanwendung jetzt auf Fehler. Rufen Sie das Crashlytics-Dashboard auf, um alle Berichte und Statistiken anzusehen und zu untersuchen.

Nächste Schritte

• Lesbare Absturzberichte erhalten: Richten Sie den automatischen Upload von Quellzuordnungen (.js.map) ein, damit in den Stacktraces Ihrer Produktion die ursprünglichen Dateinamen und Zeilennummern angezeigt werden.
• Absturzberichte anpassen: Hier erfahren Sie, wie Sie behandelte Ausnahmen melden, benutzerdefinierte Schlüssel hinzufügen, Telemetriedatensätze erzwingen und die Stichprobenerhebung konfigurieren.