Inizia a utilizzare Firebase Crashlytics

iOS+ Android Android (NDK) Flutter Unity

Se la tua app per Android contiene librerie native, puoi attivare analisi complete dello stack e report sugli arresti anomali dettagliati per il tuo codice nativo da Firebase Crashlytics con alcuni piccoli aggiornamenti alla configurazione di build dell'app.

Questa guida descrive come configurare la segnalazione degli arresti anomali con l'SDK Firebase Crashlytics per NDK.

Se vuoi scoprire come iniziare a utilizzare Crashlytics nei tuoi progetti Unity, consulta la Guida introduttiva a Unity.

Prima di iniziare

1. Se non l'hai già fatto, aggiungi Firebase al tuo progetto Android. Se non hai un'app per Android, puoi scaricare un'app di esempio.

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

   • Se il tuo progetto Firebase esistente non ha Google Analytics abilitato, puoi abilitare Google Analytics dalla scheda Integrazioni di > Impostazioni progetto nella console Firebase.

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

3. Assicurati che la tua app abbia le seguenti versioni minime richieste:

   • Gradle 8.0
   • Plug-in Android per Gradle 8.1.0
   • Plug-in Gradle dei servizi Google 4.4.1

Passaggio 1: aggiungi l'SDK Crashlytics per NDK alla tua app

Nel file Gradle (a livello di app) del modulo (di solito <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), aggiungi la dipendenza per la libreria NDK Crashlytics per Android. Ti consigliamo di utilizzare Firebase Android BoM per controllare il controllo delle versioni della libreria.

Per un'esperienza ottimale con Crashlytics, ti consigliamo di attivare Google Analytics nel tuo progetto Firebase e di aggiungere l'SDK Firebase per Google Analytics alla tua app.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.3.0"))

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk")
    implementation("com.google.firebase:firebase-analytics")
}

Utilizzando Firebase Android BoM, la tua app utilizzerà sempre versioni compatibili delle librerie Firebase Android.

(Alternativa)  Aggiungi le dipendenze della libreria Firebase senza utilizzare BoM

Se scegli di non utilizzare Firebase BoM, devi specificare la versione di ogni libreria Firebase nella relativa riga di dipendenza.

Tieni presente che se utilizzi più librerie Firebase nella tua app, ti consigliamo vivamente di utilizzare la BoM per gestire le versioni delle librerie, il che garantisce la compatibilità di tutte le versioni.

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk:20.0.2")
    implementation("com.google.firebase:firebase-analytics:23.0.0")
}

Passaggio 2: aggiungi il plug-in Gradle Crashlytics alla tua app

1. Nel file Gradle a livello di directory principale (a livello di progetto) (<project>/build.gradle.kts o <project>/build.gradle), aggiungi il plug-in Gradle Crashlytics al blocco plugins:

   Kotlin

   Stai ancora utilizzando la sintassi buildscript ? Scopri come aggiungere plug-in Firebase utilizzando questa sintassi.

   plugins {
       // Make sure that you have the AGP plugin 8.1+ dependency
       id("com.android.application") version "8.1.4" apply false
       // ...
   
       // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
       id("com.google.gms.google-services") version "4.4.3" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.6" apply false
   }

   Groovy

   Stai ancora utilizzando la sintassi buildscript ? Scopri come aggiungere plug-in Firebase utilizzando questa sintassi.

   plugins {
       // Make sure that you have the AGP plugin 8.1+ dependency
       id 'com.android.application' version '8.1.4' apply false
       // ...
   
       // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
       id 'com.google.gms.google-services' version '4.4.3' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.6' apply false
   }

   La tua app utilizza una versione precedente di Gradle? Valuta la possibilità di eseguire l'upgrade; in caso contrario, devi utilizzare la versione 2.9.9 del plug-in Gradle Crashlytics.

2. Nel file Gradle del modulo (a livello di app) (solitamente <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), aggiungi il plug-in Gradle Crashlytics:

   Kotlin

   plugins {
     id("com.android.application")
     // ...
   
     // Make sure that you have the Google services Gradle plugin
     id("com.google.gms.google-services")
   
     // Add the Crashlytics Gradle plugin
     id("com.google.firebase.crashlytics")
   }

   Groovy

   plugins {
     id 'com.android.application'
     // ...
   
     // Make sure that you have the Google services Gradle plugin
     id 'com.google.gms.google-services'
   
     // Add the Crashlytics Gradle plugin
     id 'com.google.firebase.crashlytics'
   }

Passaggio 3: aggiungi l'estensione Crashlytics alla build

Nel file Gradle del modulo (a livello di app) (di solito <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle), configura l'estensione Crashlytics.

Kotlin

import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension

// ...

android {
  // ...
  buildTypes {
      getByName("release") {
          // Add this extension
          configure<CrashlyticsExtension> {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled = true
          }
      }
  }
}

Groovy

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

Nota: la distribuzione NDK Crashlytics include i binari nativi per tutte le architetture supportate da Android NDK. Se la tua app ha come target un sottoinsieme specifico, puoi utilizzare le suddivisioni ABI per escludere le architetture non necessarie.

Passaggio 4: configura il caricamento automatico dei simboli nativi

Per produrre stack trace leggibili dagli arresti anomali dell'NDK, Crashlytics deve conoscere i simboli nei tuoi binari nativi. Il plug-in Gradle Crashlytics include l'attività uploadCrashlyticsSymbolFileBUILD_VARIANT per automatizzare questo processo.

Nota :Crashlytics supporta opzioni alternative per il caricamento dei simboli a seconda della configurazione e degli strumenti dell'app, ad esempio le build non Gradle.

1. Per accedere all'attività di caricamento automatico dei simboli, assicurati che nativeSymbolUploadEnabled sia impostato su true nel file Gradle del modulo (a livello di app).

2. Affinché i nomi dei metodi vengano visualizzati nelle analisi dello stack, devi richiamare esplicitamente l'attività uploadCrashlyticsSymbolFileBUILD_VARIANT dopo ogni build della libreria NDK. Ad esempio:

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT

3. Sia l'SDK Crashlytics per NDK sia il plug-in Gradle Crashlytics dipendono dalla presenza dell'ID build GNU all'interno degli oggetti condivisi nativi.

   Puoi verificare la presenza di questo ID eseguendo readelf -n su ogni binario. Se l'ID build non è presente, aggiungi -Wl,--build-id ai flag del sistema di build per risolvere il problema.

Passaggio 5: forza l'arresto anomalo di un test per completare la configurazione

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

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

   Puoi utilizzare il seguente codice nel file MainActivity della tua app per aggiungere un pulsante che, quando viene premuto, causa un arresto anomalo. Il pulsante è etichettato "Test Crash".

   Kotlin

   val crashButton = Button(this)
   crashButton.text = "Test Crash"
   crashButton.setOnClickListener {
      throw RuntimeException("Test Crash") // Force a crash
   }
   
   addContentView(crashButton, ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.WRAP_CONTENT))

   Java

   Button crashButton = new Button(this);
   crashButton.setText("Test Crash");
   crashButton.setOnClickListener(new View.OnClickListener() {
      public void onClick(View view) {
          throw new RuntimeException("Test Crash"); // Force a crash
      }
   });
   
   addContentView(crashButton, new ViewGroup.LayoutParams(
          ViewGroup.LayoutParams.MATCH_PARENT,
          ViewGroup.LayoutParams.WRAP_CONTENT));

2. Crea ed esegui la tua app.

3. Forza l'arresto anomalo del test per inviare il primo report sugli arresti anomali della tua app:

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

   2. Nell'app, premi il pulsante "Test Crash" che hai aggiunto utilizzando il codice sopra.

   3. Dopo l'arresto anomalo dell'app, riavviala in modo che possa inviare il report sull'arresto anomalo a Firebase.

4. Vai alla dashboard Crashlytics della console Firebase per visualizzare l'arresto anomalo del test.

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

E questo è tutto. Crashlytics ora monitora la tua app per rilevare arresti anomali e puoi visualizzare e analizzare i report e le statistiche sugli arresti anomali nella dashboard Crashlytics.

Passaggi successivi

• (Consigliato) Ricevi assistenza per il debug degli arresti anomali causati da errori di memoria nativi raccogliendo i report GWP-ASan. Questi errori relativi alla memoria possono essere associati al danneggiamento della memoria all'interno della tua app, che è la causa principale delle vulnerabilità di sicurezza delle app. Per usufruire di questa funzionalità di debug, assicurati che nella tua app sia GWP-ASan esplicitamente abilitato e che utilizzi l'ultima versione dell'SDK Crashlytics per NDK (v18.3.6+ o Firebase BoM v31.3.0+).

• Personalizza la configurazione dei report sugli arresti anomali aggiungendo report di attivazione, log, chiavi e monitoraggio degli errori non fatali.

• Esegui l'integrazione con Google Play per poter filtrare i report sugli arresti anomali della tua app per Android in base alla traccia Google Play direttamente nella dashboard Crashlytics. In questo modo puoi concentrare meglio la dashboard su build specifiche.

Risoluzione dei problemi

Se visualizzi stack trace diversi nella console Firebase e in logcat, consulta la guida alla risoluzione dei problemi.

---

Opzioni alternative per il caricamento dei simboli

Il flusso di lavoro principale in questa pagina sopra è applicabile alle build Gradle standard. Tuttavia, alcune app utilizzano una configurazione o strumenti diversi (ad esempio un processo di build diverso da Gradle). In queste situazioni, le seguenti opzioni potrebbero essere utili per caricare correttamente i simboli.

Opzione: carica i simboli per i moduli della libreria e le dipendenze esterne

Questa opzione può essere utile nelle seguenti situazioni:

• Se utilizzi un processo di compilazione NDK personalizzato in Gradle
• Se le tue librerie native sono integrate in un modulo di libreria/funzionalità o fornite da una terza parte
• Se l'attività di caricamento automatico dei simboli non va a buon fine o se nella dashboard vengono visualizzati arresti anomali senza simboli

Visualizza le istruzioni per questa opzione

L'attività di caricamento dei simboli standard Crashlytics presuppone che tu stia creando le tue librerie native come parte della build Gradle del modulo dell'app, utilizzando strumenti di build NDK standard come CMake.

Tuttavia, se utilizzi un processo di compilazione NDK personalizzato in Gradle o se le tue librerie native sono integrate in un modulo di libreria/funzionalità o fornite da terze parti, potresti dover specificare esplicitamente il percorso delle librerie non contenenti informazioni di debug. Per farlo, puoi aggiungere la proprietà unstrippedNativeLibsDir all'interno dell'estensione Crashlytics nel file di build Gradle.

1. Assicurati di aver completato le seguenti attività iniziali del flusso di lavoro principale in precedenza in questa pagina:

   1. Attivato Crashlytics nella console Firebase.

   2. Sono stati aggiunti l'SDK Crashlytics per NDK e il plug-in Gradle Crashlytics.

   3. È stata aggiunta l'estensione Crashlytics alla build.

   4. Configura il caricamento automatico dei simboli nativi.

2. Affinché l'attività di caricamento automatico dei simboli possa trovare le informazioni sui simboli, aggiungi quanto segue al file Gradle del modulo (a livello di app) (di solito <project>/<app-module>/build.gradle.kts o <project>/<app-module>/build.gradle):

   Kotlin

   import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension
   
   // ...
   
   android {
       // ...
       buildTypes {
           release {
               configure<CrashlyticsExtension> {
                   nativeSymbolUploadEnabled = true
                   unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY")
               }
           }
       }
   }

   Groovy

   // ...
   
   android {
       // ...
       buildTypes {
           release {
               firebaseCrashlytics {
                   nativeSymbolUploadEnabled true
                   unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY")
               }
           }
       }
   }

   Il plug-in Crashlytics cercherà in modo ricorsivo nella directory specificata le librerie native con estensione .so. Crashlytics, quindi estrae i simboli di debug da tutte queste librerie e li carica sui server Firebase.

   Ecco cosa puoi specificare nella proprietà unstrippedNativeLibsDir:

   • Qualsiasi argomento consentito per org.gradle.api.Project#files(Object...), inclusi: java.lang.String, java.io.File o org.gradle.api.file.FileCollection

   • Più directory per una singola variante di build fornendo un elenco o un'istanza FileCollection

   • (A partire dal plug-in Gradle v3.0.0) Accumula più directory in singoli prodotti e build.Crashlytics

   Visualizza un esempio con più directory

     buildTypes {
       release {
         configure<CrashlyticsExtension> {
           nativeSymbolUploadEnabled = true
           unstrippedNativeLibsDir = file("MY/NATIVE/LIBS")
         }
       }
       productFlavors {
         flavorDimensions += "feature"
         create("basic") {
           dimension = "feature"
           // ...
         }
         create("featureX") {
           dimension = "feature"
           configure<CrashlyticsExtension> {
             unstrippedNativeLibsDir = file("MY/FEATURE_X/LIBS")
           }
         }
       }
     }
     

   L'attività uploadCrashlyticsSymbolFilesBasicRelease caricherà solo i simboli in MY/NATIVE/LIBS, mentre uploadCrashlyticsSymbolFilesFeatureXRelease caricherà i simboli in MY/NATIVE/LIBS e MY/FEATURE_X/LIBS.

3. Infine, forza un arresto anomalo di test per completare la configurazione di Crashlytics e visualizzare i dati iniziali nella dashboard Crashlytics della console Firebase.

Opzione: carica i simboli per le build non Gradle o le librerie native non rimosse inaccessibili

Questa opzione può essere utile nelle seguenti situazioni:

• Se utilizzi un processo di build diverso da Gradle

• Se le tue librerie native non rimosse ti vengono fornite in modo tale da non essere accessibili durante le build Gradle

Visualizza le istruzioni per questa opzione

Questa opzione richiede l'esecuzione di un comando CLI Firebase quando crei una build di rilascio o qualsiasi build per cui vuoi visualizzare le analisi dello stack con simboli nella console Firebase.

1. Assicurati di aver completato le seguenti attività iniziali del flusso di lavoro principale in precedenza in questa pagina:

   1. Attivato Crashlytics nella console Firebase.

   2. Sono stati aggiunti l'SDK Crashlytics per NDK e il plug-in Gradle Crashlytics.

   Tieni presente che con questa opzione non è necessario aggiungere l'estensione firebaseCrashlytics o configurare il caricamento automatico dei simboli perché utilizzerai invece la CLI Firebase (passaggi successivi di seguito) per generare e caricare i file di simboli.

2. Configura l'ambiente e il progetto per il caricamento dei simboli:

   1. Segui le istruzioni per installare la CLI Firebase.

      Se hai già installato la CLI, assicurati di eseguire l'aggiornamento all'ultima versione.

   2. (solo per le app che utilizzano il livello API Android 30 o versioni successive) Aggiorna il modello AndroidManifest.xml della tua app per disattivare il tagging del puntatore:

      1. Seleziona la casella Android Player Settings > Publishing Settings > Build > Custom Main Manifest.

      2. Apri il modello di manifest che si trova all'indirizzo Assets/Plugins/Android/AndroidManifest.xml.

      3. Aggiungi il seguente attributo al tag dell'applicazione: <application android:allowNativeHeapPointerTagging="false" ... />

3. Crea il tuo progetto.

4. Carica le informazioni sui simboli.

   Nota: completa questo passaggio per iniziare. In futuro, completa questo passaggio ogni volta che crei una build di release o una build per cui vuoi visualizzare le analisi dello stack con simboli nella console Firebase.

   Una volta completata la build, genera un file di simboli compatibile con Crashlytics e caricalo sui server Firebase eseguendo il seguente comando CLI Firebase:

   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

     Hai bisogno di trovare l'ID app Firebase?

     Ecco due modi per trovare l'ID app Firebase:

     • Nel file google-services.json, l'ID app è il valore mobilesdk_app_id; oppure

     • Nella console Firebase, vai alle impostazioni del progetto. Scorri verso il basso fino alla scheda Le tue app, poi fai clic sull'app Firebase che ti interessa per trovare il relativo ID app.

   • PATH/TO/SYMBOLS: Il percorso del file dei simboli generato dalla CLI

     • Esportato in un progetto Android Studio:PATH/TO/SYMBOLS può essere qualsiasi directory. La CLI Firebase cercherà in modo ricorsivo nella directory specificata le librerie native con estensione .so.

     • Hai creato l'APK direttamente da Unity. PATH/TO/SYMBOLS è il percorso del file di simboli compresso generato nella directory principale del progetto al termine della build (ad esempio: myproject/myapp-1.0-v100.symbols.zip).

   Visualizza le opzioni avanzate per l'utilizzo del comando dell'interfaccia a riga di comando Firebase per la generazione e il caricamento del file di simboli

   Bandiera	Descrizione
   --generator=csym	Utilizza il generatore di file di simboli cSYM legacy anziché il generatore Breakpad predefinito Non è consigliato l'utilizzo. Ti consigliamo di utilizzare il generatore di file di simboli Breakpad predefinito.
   --generator=breakpad	Utilizza il generatore di file di simboli Breakpad Tieni presente che l'impostazione predefinita per la generazione di file di simboli è Breakpad. Utilizza questo flag solo se hai aggiunto symbolGenerator { csym() } nella configurazione della build e vuoi eseguirne l'override per utilizzare Breakpad.
   --dry-run	Genera i file di simboli, ma non li carica Questo flag è utile se vuoi ispezionare i contenuti dei file inviati.
   --debug	Fornisce informazioni di debug aggiuntive

5. Infine, forza un arresto anomalo di test per completare la configurazione di Crashlytics e visualizzare i dati iniziali nella dashboard Crashlytics della console Firebase.

   Dopo aver creato l'app nell'ambito della forzatura di un arresto anomalo, assicurati di eseguire il comando Firebase CLI crashlytics:symbols:upload per caricare il file dei simboli.

---