Ricevi report sugli arresti anomali NDK di Android

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

Questa guida descrive come configurare i report sugli arresti anomali con l'SDK Firebase Crashlytics per NDK.

Se stai cercando informazioni su come iniziare a utilizzare Crashlytics nei tuoi progetti Unity, consulta la guida introduttiva di 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 arresto anomalo, a un evento non irreversibile o ANR, devi attivare Google Analytics nel tuo progetto Firebase.

   • Se nel tuo progetto Firebase esistente Google Analytics non è abilitato, puoi attivarlo dalla scheda Integrazioni del tuo settings > Impostazioni progetto nella console Firebase.

   • Se stai creando 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

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:33.5.1"))

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

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

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:19.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}

Passaggio 2: aggiungi il plug-in Crashlytics Gradle 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

   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.2" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.2" apply false
   }

   Groovy

   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.2' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.2' apply false
   }

2. Nel file Gradle del modulo (a livello di app) (di solito <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.

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

// ...

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

Passaggio 4: configura il caricamento automatico dei simboli nativi

Per produrre tracce dello stack leggibili dagli arresti anomali NDK, Crashlytics deve conoscere i simboli nei tuoi file binari nativi. Il Crashlytics plug-in Gradle include il compito uploadCrashlyticsSymbolFileBUILD_VARIANT per automatizzare questo processo.

1. Per poter accedere all'attività per il 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 tracce dello stack, devi invocare esplicitamente il compito uploadCrashlyticsSymbolFileBUILD_VARIANT dopo ogni compilazione 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 file binario. Se l'ID build è assente, aggiungi -Wl,--build-id ai flag del sistema di compilazione per risolvere il problema.

Passaggio 5: forza un arresto anomalo del test per completare la configurazione

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

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

   Puoi utilizzare il seguente codice in MainActivity dell'app per aggiungere un pulsante all'app che, se premuto, causa un arresto anomalo. Il pulsante è etichettato come "Test di arresto anomalo".

   Kotlin+KTX

   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 di 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 di arresto anomalo" che hai aggiunto utilizzando il codice sopra riportato.

   3. Dopo che l'app si arresta in modo anomalo, riavviala in modo che possa inviare il report sul crash a Firebase.

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

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

E questo è tutto. Crashlytics sta ora monitorando la tua app per rilevare eventuali arresti anomali. Puoi visualizzare ed esaminare i report e le statistiche sugli arresti anomali nella dashboard di Crashlytics.

Passaggi successivi

• (Consigliato) Per ricevere assistenza per il debug degli arresti anomali causati da errori di memoria nativi, raccogli i report GWP-ASan. Questi errori relativi alla memoria possono essere associati a un danneggiamento della memoria all'interno della tua app, che è la causa principale delle vulnerabilità di sicurezza delle app. Per sfruttare questa funzionalità di debug, assicurati che nella tua app sia attivo GWP-ASan e che utilizzi l'SDK Crashlytics più recente per NDK (v18.3.6 o superiore o Firebase BoM v31.3.0 o superiore).

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

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

Risoluzione dei problemi

Se nella console Firebase e nel logcat vengono visualizzate tracce dello stack diverse, consulta la guida alla risoluzione dei problemi.

Opzioni alternative per il caricamento di simboli

Il flusso di lavoro principale in questa pagina è applicabile alle build Gradle standard. Tuttavia, alcune app utilizzano una configurazione o strumenti diversi (ad esempio un processo di compilazione 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 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 riesce o se vedi arresti anomali non simbolizzati nella dashboard

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

Questa opzione può essere utile nelle seguenti situazioni:

• Se utilizzi un processo di compilazione diverso da Gradle

• Se le librerie native non stripped ti vengono fornite in modo che non siano accessibili durante le build di Gradle