Inizia a utilizzare Crashlytics per il web

Seleziona la piattaforma:

iOS+ Android Android NDK Web Flutter Unity

Anteprima: Crashlytics per le app web è una versione di anteprima. Una versione di anteprima non è soggetta a SLA o norme sul ritiro e potrebbe subire modifiche incompatibili con le versioni precedenti.

Questa guida descrive come iniziare a utilizzare Firebase Crashlytics nella tua app web.

Dopo aver configurato l'SDK Firebase Crashlytics nella tua app, puoi ricevere report completi sugli arresti anomali nella console Firebase. Con Crashlytics per le app web, ricevi report sugli errori.

Importante: il supporto di Crashlytics per le app web verrà implementato nei prossimi giorni. Se non vedi ancora l'esperienza nella console Firebase, ricontrolla a breve.

Prima di iniziare

La configurazione di Crashlytics richiede attività sia nella console Firebase sia nell'IDE (ad esempio l'aggiunta della configurazione Firebase della tua app e dell'SDK Crashlytics). Per completare la configurazione, dovrai forzare un arresto anomalo di test per inviare il tuo primo report sugli arresti anomali a Firebase.

Per configurare manualmente Crashlytics nella tua app web, assicurati di aver completato i seguenti prerequisiti:

• Crea un progetto Firebase e un'app Firebase se non ne hai già uno. Se non l'hai già fatto, aggiungi Firebase al tuo progetto JavaScript.

• Assicurati che il tuo account disponga delle autorizzazioni Proprietario per il progetto. Questo è necessario per abilitare le API e i ruoli IAM necessari.

• Assicurati che il tuo progetto Firebase sia nel piano tariffario Blaze con pagamento a consumo. Crashlytics per il web utilizza Cloud Logging per l'archiviazione della telemetria e Cloud Storage per l'archiviazione delle mappe di origine, che sono prodotti a pagamento con un livello senza costi. Scopri di più sui prezzi di Logging e sui prezzi di Cloud Storage.

Passaggio 1: attiva Crashlytics per la tua app web

Crashlytics per il web utilizza Cloud Logging, Error Reporting e Cloud Storage, quindi devi abilitare queste API e configurare le autorizzazioni per il tuo progetto. Puoi attivare Crashlytics per la tua app web utilizzando la console Firebase o l'interfaccia a riga di comando Firebase.

Utilizza la console Firebase

1. Nella console Firebase, vai a DevOps e coinvolgimento > Crashlytics dashboard.

2. Seleziona la tua app web dal selettore a discesa nella parte superiore della pagina.

3. Fai clic su Configura Crashlytics e segui le istruzioni sullo schermo.

Utilizza l'interfaccia a riga di comando Firebase

Importante: anche se il supporto di Crashlytics per le app web verrà implementato nei prossimi giorni, ti consigliamo di utilizzare la console Firebase per la configurazione. Se utilizzi l'interfaccia a riga di comando Firebase in questo momento per configurare Crashlytics, potresti non essere in grado di visualizzare i tuoi arresti anomali nella dashboard di Crashlytics fino alla fine di questa settimana.

Se preferisci configurare il progetto dal terminale o utilizzare un agente di programmazione AI, puoi utilizzare l'interfaccia a riga di comando Firebase:

1. Assicurati di aver installato Firebase CLI v15.35.0 o versioni successive e di aver eseguito l'autenticazione (firebase login). Scopri come installare o aggiornare Firebase CLI.

2. Esegui questo comando per configurare Crashlytics per la tua app web:

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

   Questo comando esegue i seguenti passaggi di configurazione:

   • Verifica che il tuo progetto sia nel piano tariffario Blaze con pagamento a consumo e, se necessario, ti chiede di eseguire l'upgrade.

   • Abilita le API Crashlytics e di telemetria richieste (firebasetelemetry.googleapis.com, firebasetelemetryadmin.googleapis.com, firebasecrashlytics.googleapis.com e clienttelemetry.googleapis.com).

   • Se la chiave API della tua app web ha limitazioni relative alle API, aggiunge clienttelemetry.googleapis.com alle API consentite.

   • Configura le impostazioni di telemetria di Crashlytics per la tua app web.

   • Se eseguito in modo interattivo, ti chiede di attivare facoltativamente gli avvisi via email per i problemi nuovi e pregressi.

Passaggio 2: aggiungi e inizializza l'SDK nella tua app

1. Installa l'SDK Crashlytics:

   npm install firebase
   

2. Inizializza l'istanza FirebaseApp:

   Crea un file di utilità di configurazione centrale per utilizzare l'inizializzazione singleton. Per trovare i valori di configurazione dell'app Firebase, vai alla pagina Impostazioni progetto > Generali nella console Firebase, vai alla scheda Le tue app e seleziona la tua 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();
   

Passaggio 3: configura l'acquisizione automatica degli errori per il tuo framework

Sia i ricevitori di errori automatici del framework sia i tracker manuali utilizzano l'istanza FirebaseApp condivisa. Seleziona il framework per configurare l'acquisizione automatica degli errori:

Angular

Esegui l'integrazione con il runtime di rilevamento degli errori globali di Angular e il monitoraggio automatico dei percorsi aggiungendo provideCrashlytics(() => app) ai provider della tua app 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)
  ]
};

Nota: provideCrashlytics registra un ErrorHandler personalizzato per monitorare i crash delle zone non rilevati (Zone.js) e utilizza istanze Router interne per creare route dinamiche (come /dashboard/user/:id) anziché registrare URL letterali, mantenendo la telemetria priva di informazioni che consentono l'identificazione personale.

Next.js

Next.js 15.3 e versioni successive (consigliato): strumentazione client (instrumentation-client.ts)

Next.js 15.3 e versioni successive include la strumentazione lato client nativa tramite instrumentation-client.ts (o instrumentation-client.js). Next.js esegue questo file nel browser prima dell'inizio dell'idratazione di React.

Crea src/instrumentation-client.ts (o instrumentation-client.ts nella directory root del progetto se non utilizzi una directory src/) e inizializza Crashlytics:

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

getCrashlytics(app);

Questo singolo file inizializza Crashlytics prima dell'idratazione di React e registra automaticamente i listener di errori globali (error e unhandledrejection) senza modifiche a src/app/layout.tsx o a qualsiasi componente React.

Next.js < 15.3: lato client (layout App Router)

Per le versioni di Next.js precedenti alla 15.3, layout.tsx è un componente server per impostazione predefinita. Poiché FirebaseApp non è serializzabile, inserisci <FirebaseCrashlytics> (da @firebase/crashlytics/react per inizializzare Crashlytics e acquisire gli errori non rilevati) in un componente client (come src/components/CrashlyticsProvider.tsx) contrassegnato con la direttiva '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}
    </>
  );
}

Quindi, racchiudi il layout principale 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 (senza React Router)

Aggrega il componente dell'app principale (in genere src/App.tsx o src/main.tsx) con il componente del confine di errore <FirebaseCrashlytics>. Questo funge da ricevitore globale, gestendo i rifiuti e le eccezioni non gestiti dal browser e dalla UI di React. Aggrega tutte le gerarchie dei componenti secondari e acquisisce automaticamente le eccezioni non rilevate o gli errori di routing:

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

Se utilizzi React Router v6 o versioni successive, sostituisci il container <Routes> di React Router con <CrashlyticsRoutes>. In questo modo, i limiti degli errori vengono mappati automaticamente tra i percorsi e gli errori vengono monitorati utilizzando nomi di percorsi basati su modelli, ad esempio /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

Se la tua app utilizza TanStack Router, inizializza Crashlytics con getCrashlytics(app) e collega la registrazione degli errori predefinita direttamente all'interno della configurazione dell'istanza 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: la chiamata a getCrashlytics(app) registra automaticamente i listener globali per gli errori della finestra non rilevati e i rifiuti di promesse non gestiti, mentre defaultOnCatch acquisisce gli errori rilevati durante il routing e il rendering dei componenti all'interno di TanStack Router.

(Facoltativo) Passaggio 4: configura il controllo delle versioni dell'app

Ti consigliamo vivamente di aggiungere una stringa di versione chiara alle build della tua app web, in modo da poter isolare le regressioni in deployment specifici. Passa appVersion in CrashlyticsOptions durante l'inizializzazione dell'SDK Crashlytics per il tuo framework (utilizzando una stringa di release o una variabile di ambiente in fase di build, ad esempio process.env.NEXT_PUBLIC_APP_VERSION o import.meta.env.VITE_APP_VERSION):

Angular

Passa un oggetto CrashlyticsOptions con appVersion come secondo argomento a 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 e versioni successive (consigliato): strumentazione client (instrumentation-client.ts)

Passa un oggetto CrashlyticsOptions con appVersion come secondo argomento a 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: lato client (layout App Router)

Passa crashlyticsOptions con appVersion a <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 (senza React Router)

Passaggio crashlyticsOptions con appVersion a <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+)

Passaggio crashlyticsOptions con appVersion a <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

Passa un oggetto CrashlyticsOptions con appVersion come secondo argomento 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);
  },
});

Passaggio 5: forza un arresto anomalo di test

Per completare la configurazione di Crashlytics e visualizzare i dati iniziali nella dashboard di Crashlytics della console Firebase, devi forzare un arresto anomalo di test.

1. Aggiungi alla tua app il codice che puoi utilizzare per forzare un arresto anomalo di test.

   Aggiungi un pulsante di test o un trigger di route alla tua app React, Next.js o Angular che genera un errore di runtime quando viene fatto clic:

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

   Se hai configurato l'acquisizione automatica degli errori con <FirebaseCrashlytics> (React o Next.js), provideCrashlytics (Angular) o <CrashlyticsRoutes> (React Router), la generazione di questo errore acquisisce automaticamente l'eccezione e ne pianifica il caricamento.

2. Crea ed esegui l'app, quindi attiva l'errore di test in modo che l'app invii il primo report sugli arresti anomali a Firebase.

3. Nella console Firebase, vai alla dashboard DevOps e coinvolgimento > Crashlytics per verificare la presenza del report sugli arresti anomali di test:

   1. Seleziona la tua app web dal selettore a discesa nella parte superiore della pagina.

   2. Aggiorna la pagina. L'eccezione di test dovrebbe essere visualizzata nella tabella Problemi entro pochi minuti.

Se hai aggiornato la console e continui a non vedere l'arresto anomalo del test dopo 5-10 minuti, consulta Risolvi i problemi di configurazione.

Crashlytics sta monitorando la tua app web per rilevare eventuali errori. Visita la dashboard di Crashlytics per visualizzare ed esaminare tutti i report e le statistiche.

Passaggi successivi

• Genera report sugli arresti anomali leggibili: configura il caricamento automatico dei file di mappatura di origine (.js.map) in modo che le analisi dello stack di produzione mostrino i nomi file e i numeri di riga originali.
• Personalizza i report sugli arresti anomali: scopri come segnalare le eccezioni gestite, aggiungere chiavi personalizzate, forzare lo svuotamento dei record di telemetria e configurare il campionamento.