Recevoir des rapports d'erreur du NDK Android

Si votre application Android contient des bibliothèques natives : Vous pouvez activer les traces de la pile complète et les rapports d'erreur détaillés pour votre code natif à partir de Firebase Crashlytics en apportant quelques petites mises à jour au build de votre application configuration.

Ce guide explique comment configurer les rapports d'erreur à l'aide de SDK Firebase Crashlytics pour NDK

Pour savoir comment commencer à utiliser Crashlytics dans vos projets Unity, consultez le guide de démarrage d'Unity.

Avant de commencer

1. Si ce n'est pas encore fait, ajoutez Firebase à votre projet Android. Si vous n'avez pas d'application Android, vous pouvez télécharger Une application exemple

2. Recommandé: Pour obtenir automatiquement journaux de fil d'Ariane pour comprendre les actions des utilisateurs ayant entraîné un plantage, une erreur non fatale ou une erreur ANR, vous devez activer Google Analytics dans votre projet Firebase.

   • Si votre projet Firebase existant ne comporte pas de ressources Google Analytics vous pouvez activer Google Analytics depuis la Intégrations de votre > Paramètres du projet dans la console Firebase.

   • Si vous créez un projet Firebase, activez Google Analytics au cours du workflow de création du projet.

3. Assurez-vous que votre application dispose des versions minimales requises suivantes :

   • Gradle 8.0
   • Plug-in Android Gradle 8.1.0
   • Plug-in Gradle des services Google 4.4.1

Étape 1: Ajoutez le SDK Crashlytics pour NDK à votre application

Dans le fichier Gradle de votre module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), Ajoutez la dépendance pour la bibliothèque NDK Crashlytics pour Android. Nous vous recommandons d'utiliser Firebase Android BoM pour contrôler la gestion des versions des bibliothèques.

Pour une expérience optimale avec Crashlytics, nous vous recommandons activation de Google Analytics dans votre projet Firebase et d'ajouter le SDK Firebase pour Google Analytics à votre application.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.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")
}

En utilisant Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.

(Alternative) Ajouter des dépendances de la bibliothèque Firebase sans utiliser l'BoM

Si vous choisissez de ne pas utiliser Firebase BoM, vous devez spécifier chaque version de la bibliothèque Firebase dans sa ligne de dépendance.

Notez que si vous utilisez plusieurs bibliothèques Firebase dans votre application, recommandent d'utiliser BoM pour gérer les versions de la bibliothèque, ce qui garantit que toutes les versions sont compatibles.

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

Vous recherchez un module de bibliothèque spécifique à Kotlin ? À partir d'octobre 2023 (Firebase BoM 32.5.0), les développeurs Kotlin et Java peuvent dépendre du module de bibliothèque principal (pour en savoir plus, consultez les questions fréquentes sur cette initiative).

Étape 2: Ajoutez le plug-in Gradle Crashlytics à votre application

1. Dans votre fichier Gradle au niveau racine (au niveau du projet) (<project>/build.gradle.kts ou <project>/build.gradle), ajoutez la Crashlytics du plug-in Gradle au bloc plugins:

   Kotlin

   Utilisez-vous toujours buildscript la syntaxe ? Découvrez comment Ajouter des plug-ins Firebase à l'aide de cette syntaxe.

   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

   Utilisez-vous toujours buildscript la syntaxe ? Découvrez comment ajouter des plug-ins Firebase à l'aide de cette syntaxe.

   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
   }
   

   Votre application utilise-t-elle une version antérieure de Gradle ? Envisagez de mettre à niveau. Dans le cas contraire, vous devez utiliser la version 2.9.9 du plug-in Gradle Crashlytics.

2. Dans le fichier Gradle de votre module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), Ajoutez le 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'
   }

Étape 3: Ajoutez l'extension Crashlytics à votre build

Dans le fichier Gradle de votre module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <project>/<app-module>/build.gradle), configurez l'extension 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
          }
      }
  }
}

Remarque :La distribution du NDK Crashlytics inclut des binaires natifs pour tous architectures compatibles avec NDK Android. Si votre application cible un sous-ensemble spécifique, vous pouvez utiliser Divisions de l'ABI pour exclure les architectures inutiles.

Étape 4: Configurez l'importation automatique de symboles natifs

Pour produire des traces de pile lisibles à partir de plantages du NDK, Crashlytics doit connaître sur les symboles de vos binaires natifs. Plug-in Gradle Crashlytics inclut l'élément uploadCrashlyticsSymbolFileBUILD_VARIANT pour automatiser ce processus.

Remarque :Crashlytics est compatible avec autres options pour importer des symboles en fonction de la configuration et des outils de votre application, tels que les builds autres que Gradle.

1. Pour pouvoir accéder à la tâche d'importation automatique des symboles, assurez-vous que nativeSymbolUploadEnabled est défini sur true dans votre module (au niveau de l'application) ; Gradle.

2. Pour que les noms des méthodes apparaissent dans les traces de la pile, vous devez appeler explicitement le uploadCrashlyticsSymbolFileBUILD_VARIANT après chaque compilation de votre bibliothèque NDK. Exemple :

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT
   

3. Le SDK Crashlytics pour le NDK et le plug-in Gradle Crashlytics dépend de la présence de l'ID de build GNU dans les objets partagés natifs.

   Vous pouvez vérifier la présence de cet ID en exécutant readelf -n sur chaque binaire. Si l'ID de build est absente, ajoutez -Wl,--build-id au fichier pour résoudre le problème.

Étape 5: Forcez un test de plantage pour terminer la configuration

Pour terminer la configuration de Crashlytics et voir les données initiales dans le tableau de bord Crashlytics de la console Firebase, vous devez forcer un test le plantage.

1. Ajoutez du code à votre application que vous pouvez utiliser pour forcer un plantage de test.

   Vous pouvez utiliser le code suivant dans le fichier MainActivity de votre application pour ajouter un bouton à votre application qui, si vous appuyez dessus, provoque un plantage. Le bouton est étiqueté "Tester le plantage".

   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. Créez et exécutez votre application.

3. Forcez le plantage du test pour envoyer le premier rapport d'erreur de votre application:

   1. Ouvrez votre application depuis votre appareil de test ou votre émulateur.

   2. Dans votre application, appuyez sur le bouton "Tester le plantage" que vous avez ajouté à l'aide du code ci-dessus.

   3. Après un plantage, redémarrez-la pour qu'elle puisse envoyer le plantage dans Firebase.

4. Accédez au tableau de bord Crashlytics de la Firebase pour voir le plantage du test.

   Si vous avez actualisé la console et que le plantage du test ne s'affiche toujours pas après cinq minutes, Activer la journalisation du débogage pour voir si votre appli envoie des rapports d'erreur.

Et voilà ! Crashlytics surveille désormais votre application pour détecter les plantages, et vous pouvez consulter et analyser les rapports d'erreur et les statistiques dans le Tableau de bord Crashlytics.

Étapes suivantes

• (Recommandé) Obtenez de l'aide pour déboguer les plantages causés par des erreurs de mémoire native en collecter Rapports GWP-ASan Ces erreurs liées à la mémoire peuvent être associées à une corruption de la mémoire dans votre application, qui est la principale cause de failles de sécurité des applications. Pour profiter de cette fonctionnalité de débogage, assurez-vous que votre application a GWP-ASan est explicitement activé et utilise le dernier SDK Crashlytics pour NDK (version 18.3.6+ ou ultérieure Firebase BoM v31.3.0+).

• Personnalisez la configuration des rapports d'erreur en ajoutant des rapports, des journaux, des clés et un suivi des erreurs non fatales.

• Intégrez Google Play pour pouvoir filtrer les rapports de plantage de votre application Android par trace Google Play directement dans le tableau de bord Crashlytics. Vous pouvez ainsi concentrer votre tableau de bord sur des builds spécifiques.

Dépannage

Si vous voyez des traces de pile différentes dans la console Firebase et dans Logcat, consultez le guide de dépannage.

---

Autres options d'importation de symboles

Le workflow principal de cette page ci-dessus s'applique aux builds Gradle standards. Cependant, certaines applications utilisent une configuration ou des outils différents (par exemple, un build autre que Gradle). Dans ces situations, les options suivantes peuvent être utiles pour bien importer des symboles.

Option : Importer des symboles pour les modules de bibliothèque et les dépendances externes

Cette option peut s'avérer utile dans les situations suivantes :

• Si vous utilisez un processus de compilation NDK personnalisé dans Gradle
• Si vos bibliothèques natives sont compilées dans un module de bibliothèque/fonction ou fournies par un tiers
• Si la tâche d'importation automatique des symboles ou que vous constatez des plantages non symbolisés dans le tableau de bord

Afficher les instructions pour cette option

La tâche d'importation de symboles Crashlytics standard suppose que vous compilez vos bibliothèques natives dans le cadre de la compilation Gradle de votre module d'application, à l'aide d'outils de compilation NDK standards tels que CMake.

Toutefois, si vous utilisez un processus de compilation du NDK personnalisé dans Gradle, ou si vos bibliothèques natives sont compilées dans un module de bibliothèque/fonctionnalité ou fournies par un tiers, vous devrez peut-être spécifier explicitement le chemin d'accès à vos bibliothèques non supprimées. Pour ce faire, vous pouvez ajouter unstrippedNativeLibsDir dans l'extension Crashlytics de votre fichier de compilation Gradle.

1. Assurez-vous d'avoir effectué les tâches initiales suivantes le workflow précédent sur cette page:

   1. Crashlytics a été activé dans la console Firebase.

   2. Ajout de la SDK Crashlytics pour NDK et Plug-in Gradle Crashlytics.

   3. Ajout de l'extension Crashlytics à votre build.

   4. Configurez l'importation automatique des symboles natifs.

2. Pour que la tâche d'importation automatique des symboles puisse trouver votre symbole informations, ajoutez ce qui suit au fichier Gradle du module (au niveau de l'application) (généralement <project>/<app-module>/build.gradle.kts ou <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")
               }
           }
       }
   }
   

   Le plug-in Crashlytics recherche de manière récursive le répertoire spécifié pour les bibliothèques natives avec une extension .so. Crashlytics extrait ensuite les symboles de débogage de toutes ces bibliothèques et les importe sur les serveurs Firebase.

   Voici ce que vous pouvez spécifier dans la propriété unstrippedNativeLibsDir:

   • Tout argument autorisé pour org.gradle.api.Project#files(Object...), y compris: java.lang.String, java.io.File ou org.gradle.api.file.FileCollection

   • Plusieurs répertoires pour un même type de compilation en fournissant une liste ou FileCollection instance

   • (À partir du plug-in Crashlytics Gradle v3.0.0) Accumuler plusieurs répertoires dans des produits individuels et de créer des types.

   Voir un exemple avec plusieurs répertoires

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

   La tâche uploadCrashlyticsSymbolFilesBasicRelease n'importera que les dans MY/NATIVE/LIBS, mais uploadCrashlyticsSymbolFilesFeatureXRelease importera les symboles dans les deux MY/NATIVE/LIBS et MY/FEATURE_X/LIBS.

3. Enfin, forcez un plantage de test pour terminer la configuration de Crashlytics et afficher les données initiales dans le tableau de bord Crashlytics de la console Firebase.

Option: importer des symboles pour des builds non-Gradle ou des bibliothèques natives complètes inaccessibles

Cette option peut être utile dans les situations suivantes:

• Si vous utilisez un processus de compilation autre que Gradle

• Si vos bibliothèques natives non supprimées vous sont fournies de manière à ce qu'elles ne soient pas accessibles lors des compilations Gradle

Afficher les instructions pour cette option

Cette option nécessite que vous exécutiez une commande CLI Firebase lorsque vous créez un build ou tout build pour lequel vous souhaitez afficher des traces de pile symbolisées dans la console Firebase.

1. Assurez-vous d'avoir effectué les tâches initiales suivantes le workflow précédent sur cette page:

   1. Crashlytics a été activé dans la console Firebase.

   2. Ajout de la SDK Crashlytics pour NDK et Plug-in Gradle Crashlytics.

   Notez qu'avec cette option, vous n'avez pas besoin d'ajouter le firebaseCrashlytics ou configurez l'importation automatique des symboles. La CLI Firebase (voir les étapes ci-dessous) pour générer et importer votre symbole .

2. Configurez votre environnement et votre projet pour l'importation de symboles :

   1. Suivez les instructions pour installer la CLI Firebase.

      Si vous avez déjà installé la CLI, assurez-vous de installer la dernière version.

   2. (uniquement pour les applications utilisant le niveau d'API Android 30 ou version ultérieure) Mettez à jour le paramètre Modèle AndroidManifest.xml pour désactiver le balisage du pointeur:

      1. Cochez la case Android Player Settings > Publishing Settings > Build > Custom Main Manifest (Paramètres du lecteur Android > Paramètres de publication > Compilation > Fichier manifeste principal personnalisé).

      2. Ouvrez le modèle de fichier manifeste situé à l'adresse Assets/Plugins/Android/AndroidManifest.xml

      3. Ajoutez l'attribut suivant au tag d'application: <application android:allowNativeHeapPointerTagging="false" ... />

3. Compilez votre projet.

4. Importez les informations sur vos symboles.

   Remarque :Effectuez cette étape pour commencer. Ensuite, à l'avenir, effectuez cette chaque fois que vous créez un build ou un build pour lequel souhaitez voir les traces de pile décodées dans la console Firebase.

   Une fois la compilation terminée, générez un symbole compatible avec Crashlytics et l'importer sur les serveurs Firebase en exécutant la commande suivante : Commande CLI Firebase:

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

   • FIREBASE_APP_ID : votre ID d'application Android Firebase (et non votre nom de package)
     Exemple d'ID d'application Android Firebase : 1:567383003300:android:17104a2ced0c9b9b

     Vous avez besoin de votre ID d'application Firebase ?

     Vous pouvez trouver votre ID d'application Firebase de deux façons:

     • Dans votre fichier google-services.json, l'ID de votre application correspond au Valeur mobilesdk_app_id ; ou

     • Dans la console Firebase, accédez à vos Paramètres du projet. Faites défiler la page jusqu'à la fiche Vos applications, puis cliquez sur les applications Firebase de votre choix Application pour trouver son ID.

   • PATH/TO/SYMBOLS: chemin d'accès au fichier de symboles généré par CLI

     • Exportées vers un projet Android Studio : PATH/TO/SYMBOLS peut correspondre à n'importe quel répertoire. La CLI Firebase recherche de manière récursive les bibliothèques natives dans le répertoire spécifié avec une extension .so.

     • Création de l'APK directement depuis Unity : PATH/TO/SYMBOLS est le chemin d'accès au fichier de symboles compressé. généré dans le répertoire racine du projet une fois la compilation terminée (par exemple: myproject/myapp-1.0-v100.symbols.zip).

   Consultez les options avancées d'utilisation des Commande CLI Firebase pour générer et importer des fichiers de symboles

   Option	Description
   --generator=csym	Utilise l'ancien générateur de fichiers de symboles cSYM au lieu de générateur de Breakpad par défaut Utilisation déconseillée Nous vous recommandons d'utiliser Générateur de fichiers de symboles Breakpad.
   --generator=breakpad	Utilise le générateur de fichiers de symboles Breakpad Notez que le paramètre par défaut pour la génération de fichiers de symboles est Breakpad. N'utilisez cet indicateur que si vous avez ajouté symbolGenerator { csym() } dans votre configuration de compilation et que vous souhaitez la remplacer Breakpad à la place.
   --dry-run	Génère les fichiers de symboles, mais ne les importe pas Cet indicateur est utile si vous souhaitez inspecter le contenu des fichiers envoyés.
   --debug	Fournit des informations de débogage supplémentaires

5. Enfin, forcez un plantage test pour terminer la configuration. Crashlytics et afficher les données initiales dans le tableau de bord Crashlytics de la console Firebase.

   Une fois que vous avez compilé votre application pour forcer un plantage, assurez-vous d'exécuter le Commande crashlytics:symbols:upload de la CLI Firebase pour importer votre symbole .

---