Inizia a utilizzare Crashlytics per Flutter

Seleziona la piattaforma: iOS+ Android Android NDK Flutter Unity


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

Dopo aver configurato il plug-in Flutter Crashlytics nella tua app, puoi ricevere report completi sugli arresti anomali nella console Firebase.

La configurazione di Crashlytics prevede l'utilizzo sia di uno strumento a riga di comando sia dell'IDE. Per completare la configurazione, dovrai forzare l'attivazione di un'eccezione di test per inviare il tuo primo report sugli arresti anomali a Firebase.

Prima di iniziare

  1. Se non l'hai ancora fatto, configura e inizializza Firebase nel tuo progetto Flutter.

  2. Consigliato: per ricevere automaticamente i log dei breadcrumb per comprendere le azioni degli utenti che hanno portato a un evento di arresto anomalo, non irreversibile o ANR, devi attivare Google Analytics nel tuo progetto Firebase.

    • Se generi un nuovo progetto Firebase, abilita Google Analytics durante il flusso di lavoro di creazione del progetto.

    • Se utilizzi un progetto Firebase esistente in cui non è abilitato Google Analytics, puoi attivarlo nella pagina Impostazioni > Integrazioni della console Firebase.

    Tieni presente che i log dei breadcrumb sono disponibili per tutte le piattaforme Android e Apple supportate da Crashlytics (ad eccezione di watchOS).

Passaggio 1: aggiungi Crashlytics al tuo progetto Flutter

  1. Dalla directory principale del progetto Flutter, esegui questo comando per installare il plug-in Flutter per Crashlytics.

    Per sfruttare i log dei breadcrumb, aggiungi anche il plug-in Flutter per Google Analytics alla tua app. Assicurati che Google Analytics sia abilitato nel tuo progetto Firebase.

    flutter pub add firebase_crashlytics && flutter pub add firebase_analytics

  2. Dalla directory principale del progetto Flutter, esegui questo comando:

    flutterfire configure

    L'esecuzione di questo comando garantisce che la configurazione Firebase della tua app Flutter sia aggiornata e, per Android, aggiunge il plug-in Gradle Crashlytics richiesto alla tua app.

  3. Al termine, ricrea il progetto Flutter:

    flutter run

  4. (Facoltativo) Se il tuo progetto Flutter utilizza il flag --split-debug-info (e, facoltativamente, anche il flag --obfuscate), sono necessari passaggi aggiuntivi per mostrare analisi dello stack leggibili per le tue app.

    • Piattaforme Apple: assicurati che il tuo progetto utilizzi la configurazione della versione consigliata (Flutter 3.12.0+ e plug-in Flutter Crashlytics 3.3.4+) in modo che il progetto possa generare e caricare automaticamente i simboli Flutter (file dSYM) su Crashlytics.

    • Android: utilizza l'interfaccia a riga di comando Firebase (v.11.9.0 e successive) per caricare i simboli di debug di Flutter. Devi caricare i simboli di debug prima di segnalare un arresto anomalo da una build di codice offuscato.

      Dalla directory principale del progetto Flutter, esegui questo comando:

      firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

      • FIREBASE_APP_ID: l'ID app Firebase per Android (non il nome del pacchetto)
        Esempio di ID app Firebase per Android: 1:567383003300:android:17104a2ced0c9b9b

      • PATH/TO/symbols: la stessa directory che passi al flag --split-debug-info durante la creazione dell'applicazione

Passaggio 2: configura i gestori degli arresti anomali

Puoi rilevare automaticamente tutti gli errori generati all'interno del framework Flutter eseguendo l'override di FlutterError.onError con FirebaseCrashlytics.instance.recordFlutterFatalError:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();

  // Pass all uncaught "fatal" errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

Per rilevare gli errori asincroni non gestiti dal framework Flutter, utilizza PlatformDispatcher.instance.onError:

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

Per esempi di come gestire altri tipi di errori, consulta Personalizza i report sugli arresti anomali.

Passaggio 3: forza un arresto anomalo di prova per completare la configurazione

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

  1. Aggiungi alla tua app un codice che puoi utilizzare per forzare la generazione di un'eccezione di test.

    Se hai aggiunto un gestore degli errori che chiama FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) all'elemento Zone di primo livello, puoi utilizzare il seguente codice per aggiungere un pulsante alla tua app che, se premuto, genera un'eccezione di test:

    TextButton(
    onPressed: () => throw Exception(),
    child: const Text("Throw Test Exception"),
),

  2. Crea ed esegui la tua app.

  3. Forza l'attivazione dell'eccezione di test per inviare il primo report della tua app:

    1. Apri l'app dal dispositivo di test o dall'emulatore.

    2. Nell'app, premi il pulsante di test delle eccezioni che hai aggiunto utilizzando il codice riportato sopra.

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

    Se hai aggiornato la console e non vedi ancora l'arresto anomalo di test dopo cinque minuti, attiva il logging di debug per verificare se l'app invia report sugli arresti anomali.


È tutto. Crashlytics ora monitora la tua app per rilevare arresti anomali e, su Android, errori non irreversibili e ANR. Visita la dashboard di Crashlytics per visualizzare ed esaminare tutti i report e le statistiche.

Passaggi successivi