Si votre application Android contient des bibliothèques natives , vous pouvez activer les traces de pile complètes et les rapports d'erreur détaillés pour votre code natif à partir de Firebase Crashlytics avec quelques petites mises à jour de la configuration de build de votre application.
Ce guide décrit comment configurer les rapports d'incidents avec le SDK Firebase Crashlytics pour NDK.
Si vous cherchez comment démarrer avec Crashlytics dans vos projets Unity, consultez le guide de démarrage Unity .
Avant que tu commences
Si vous ne l'avez pas déjà fait, ajoutez Firebase à votre projet Android. Si vous n'avez pas d'application Android, vous pouvez télécharger un exemple d'application .
Recommandé : pour obtenir des fonctionnalités telles que des utilisateurs sans crash, des journaux de fil d'Ariane et des alertes de vitesse, vous devez activer Google Analytics dans votre projet Firebase.
Si Google Analytics n'est pas activé sur votre projet Firebase existant, vous pouvez activer Google Analytics à partir de l' onglet Intégrations de votre
Si vous créez un nouveau projet Firebase, activez Google Analytics pendant le workflow de création du projet.
É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 le Crashlytics NDK bibliothèque pour Android. Nous vous recommandons d'utiliser la BoM Android Firebase pour contrôler la gestion des versions de la bibliothèque.Pour une expérience optimale avec Crashlytics, nous vous recommandons d'activer 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:32.6.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 la BoM
Si vous choisissez de ne pas utiliser la BoM Firebase, 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, nous vous recommandons fortement d'utiliser la BoM pour gérer les versions de 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:18.6.0") implementation("com.google.firebase:firebase-analytics:21.5.0") }
Étape 2 : Ajoutez le plugin Crashlytics Gradle à votre application
Dans votre fichier Gradle au niveau racine (au niveau du projet) (
<project>/build.gradle.kts
ou<project>/build.gradle
), ajoutez le plugin Crashlytics Gradle au blocplugins
:Kotlin
plugins { id("com.android.application") version "7.3.0" apply false // ... // Make sure that you have the Google services Gradle plugin dependency id("com.google.gms.google-services") version "4.4.0" apply false // Add the dependency for the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") version "2.9.9" apply false }
Groovy
plugins { id 'com.android.application' version '7.3.0' apply false // ... // Make sure that you have the Google services Gradle plugin dependency id 'com.google.gms.google-services' version '4.4.0' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '2.9.9' apply false }
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 plugin Crashlytics Gradle :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 } } } }
Étape 4 : Configurer le téléchargement automatique des symboles natifs
Pour produire des traces de pile lisibles à partir des plantages du NDK, Crashlytics doit connaître les symboles de vos binaires natifs. Le plugin Crashlytics Gradle inclut la tâche uploadCrashlyticsSymbolFile BUILD_VARIANT
pour automatiser ce processus.
Afin que vous puissiez accéder à la tâche de téléchargement automatisé de symboles, assurez-vous que
nativeSymbolUploadEnabled
est défini surtrue
dans le fichier Gradle de votre module (au niveau de l'application).Pour que les noms de méthodes apparaissent dans vos traces de pile, vous devez appeler explicitement la tâche
uploadCrashlyticsSymbolFile BUILD_VARIANT
après chaque build de votre bibliothèque NDK. Par exemple:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
Le SDK Crashlytics pour NDK et le plugin Crashlytics Gradle dépendent 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 identifiant en exécutant
readelf -n
sur chaque binaire. Si l'ID de build est absent, ajoutez-Wl,--build-id
aux indicateurs de votre système de build pour résoudre le problème.
Étape 5 : Forcer un crash de test pour terminer la configuration
Pour terminer la configuration de Crashlytics et consulter les données initiales dans le tableau de bord Crashlytics de la console Firebase, vous devez forcer un crash de test.
Ajoutez du code à votre application que vous pouvez utiliser pour forcer un crash de test.
Vous pouvez utiliser le code suivant dans
MainActivity
de votre application pour ajouter un bouton à votre application qui, lorsqu'il est enfoncé, provoque un crash. Le bouton est intitulé "Test Crash".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));
Créez et exécutez votre application.
Forcez le crash du test afin d'envoyer le premier rapport de crash de votre application :
Ouvrez votre application à partir de votre appareil de test ou de votre émulateur.
Dans votre application, appuyez sur le bouton "Test Crash" que vous avez ajouté à l'aide du code ci-dessus.
Après le crash de votre application, redémarrez-la afin qu'elle puisse envoyer le rapport de crash à Firebase.
Accédez au tableau de bord Crashlytics de la console Firebase pour voir votre crash de test.
Si vous avez actualisé la console et que vous ne voyez toujours pas le plantage du test après cinq minutes, activez la journalisation du débogage pour voir si votre application envoie des rapports de plantage.
Et c'est tout! Crashlytics surveille désormais les plantages de votre application, et vous pouvez afficher et étudier les rapports de plantage et les statistiques dans le tableau de bord Crashlytics.
Prochaines étapes
(Recommandé) Obtenez de l'aide pour déboguer les plantages causés par des erreurs de mémoire native en collectant les rapports GWP-ASan . Ces erreurs liées à la mémoire peuvent être associées à une corruption de la mémoire au sein de votre application, qui est la principale cause de vulnérabilités de sécurité des applications. Pour profiter de cette fonctionnalité de débogage, assurez-vous que GWP-ASan est explicitement activé dans votre application et qu'elle utilise le dernier SDK Crashlytics pour NDK (v18.3.6+ ou Firebase BoM v31.3.0+).
Personnalisez la configuration de votre rapport d'erreur en ajoutant des rapports opt-in, des journaux, des clés et un suivi des erreurs non fatales.
Intégrez Google Play afin de pouvoir filtrer les rapports d'erreur de votre application Android par suivi Google Play directement dans le tableau de bord Crashlytics. Cela vous permet de mieux concentrer votre tableau de bord sur des builds spécifiques.
Dépannage
Si vous voyez différentes traces de pile dans la console Firebase et dans le logcat, reportez-vous au Guide de dépannage .
Options alternatives pour télécharger des symboles
Le flux de travail principal sur cette page ci-dessus est applicable aux versions Gradle standard. Cependant, certaines applications utilisent une configuration ou des outils différents (par exemple un processus de build autre que Gradle). Dans ces situations, les options suivantes peuvent être utiles pour réussir le téléchargement des symboles.
Option : Télécharger des symboles pour les modules de bibliothèque et les dépendances externes
Cette option peut être utile dans les situations suivantes :
- Si vous utilisez un processus de construction NDK personnalisé dans Gradle
- Si vos bibliothèques natives sont construites dans un module de bibliothèque/fonctionnalité ou fournies par un tiers
- Si la tâche de téléchargement automatique des symboles échoue ou si vous constatez des plantages non symbolisés dans le tableau de bord
La tâche standard de téléchargement de symboles Crashlytics suppose que vous créez vos bibliothèques natives dans le cadre de la build Gradle de votre module d'application, à l'aide d'outils de build NDK standard tels que CMake.
Cependant, si vous utilisez un processus de construction NDK personnalisé dans Gradle, ou si vos bibliothèques natives sont créé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 la propriété unstrippedNativeLibsDir
dans l'extension Crashlytics dans votre fichier de build Gradle.
Assurez-vous d'avoir effectué les tâches initiales suivantes du flux de travail principal plus haut sur cette page :
Pour que la tâche de téléchargement automatique de symboles puisse trouver les informations de votre symbole, ajoutez ce qui suit au 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
):Kotlin
import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension // ... android { // ... buildTypes { release { configure
{ nativeSymbolUploadEnabled = true unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } } Groovy
// ... android { // ... buildTypes { release { firebaseCrashlytics { nativeSymbolUploadEnabled true unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } }
Le plugin Crashlytics recherchera récursivement dans le répertoire spécifié les bibliothèques natives avec une extension
.so
. Crashlytics extrait ensuite les symboles de débogage de toutes ces bibliothèques et les télécharge 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...)
, notamment :java.lang.String
,java.io.File
, ouorg.gradle.api.file.FileCollection
Plusieurs répertoires pour une seule version de build en fournissant une liste ou une instance
FileCollection
Enfin, forcez un crash de test pour terminer la configuration de Crashlytics et voir les données initiales dans le tableau de bord Crashlytics de la console Firebase.
Option : Télécharger des symboles pour les versions non-Gradle ou les bibliothèques natives non supprimées inaccessibles
Cette option peut être utile dans les situations suivantes :
Si vous utilisez un processus de build autre que Gradle
Si vos bibliothèques natives non supprimées vous sont fournies d'une manière telle qu'elles ne sont pas accessibles lors des builds Gradle
Cette option nécessite que vous exécutiez une commande CLI Firebase lorsque vous créez une version de version ou toute version pour laquelle vous souhaitez voir les traces de pile symbolisées dans la console Firebase.
Assurez-vous d'avoir effectué les tâches initiales suivantes du flux de travail principal plus haut sur cette page :
Ajout du SDK Crashlytics pour NDK et du plugin Crashlytics Gradle .
Notez qu'avec cette option, vous n'avez pas besoin d'ajouter l'extension
firebaseCrashlytics
ou de configurer le téléchargement automatique de symboles, car vous utiliserez plutôt la CLI Firebase (étapes suivantes ci-dessous) pour générer et télécharger vos fichiers de symboles.Configurez votre environnement et votre projet pour le téléchargement de symboles :
Suivez les instructions pour installer la CLI Firebase .
Si vous avez déjà installé la CLI, assurez-vous de mettre à jour vers sa dernière version .
(uniquement pour les applications utilisant le niveau d'API Android 30+) Mettez à jour le modèle
AndroidManifest.xml
de votre application pour désactiver le balisage du pointeur :Cochez la case Paramètres du lecteur Android > Paramètres de publication > Construire > Manifeste principal personnalisé .
Ouvrez le modèle de manifeste situé dans
Assets/Plugins/Android/AndroidManifest.xml
.Ajoutez l'attribut suivant à la balise d'application :
<application android:allowNativeHeapPointerTagging="false" ... />
Construisez votre projet.
Téléchargez les informations de vos symboles.
Une fois votre build terminée, générez un fichier de symboles compatible Crashlytics et téléchargez-le sur les serveurs Firebase en exécutant la commande Firebase CLI suivante :
firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS
FIREBASE_APP_ID : ID de votre application Firebase Android (pas le nom de votre package)
Exemple d'ID d'application Android Firebase :1:567383003300:android:17104a2ced0c9b9b
Voici deux façons de trouver votre identifiant d'application Firebase :
Dans votre fichier
google-services.json
, votre identifiant d'application est la valeurmobilesdk_app_id
; ouDans la console Firebase, accédez aux paramètres de votre projet . Faites défiler jusqu'à la carte Vos applications , puis cliquez sur l'application Firebase souhaitée pour trouver son identifiant d'application.
PATH/TO/SYMBOLS : Le chemin d'accès au fichier de symboles généré par la CLI
Exporté vers un projet Android Studio — PATH/TO/SYMBOLS peut être n'importe quel répertoire. La CLI Firebase recherchera de manière récursive dans le répertoire spécifié les bibliothèques natives avec une extension
.so
.Créez l'APK directement depuis Unity — PATH/TO/SYMBOLS est le chemin du fichier de symboles compressé généré dans le répertoire racine du projet lorsque votre build est terminé (par exemple :
myproject/myapp-1.0-v100.symbols.zip
).
Afficher les options avancées d'utilisation de la commande Firebase CLI pour la génération et le téléchargement de fichiers de symboles
Drapeau Description --generator=csym
Utilise l'ancien générateur de fichiers de symboles cSYM au lieu du générateur Breakpad par défaut
Utilisation non recommandée. Nous vous recommandons d'utiliser le générateur de fichiers de symboles Breakpad par défaut.
--generator=breakpad
Utilise le générateur de fichiers de symboles Breakpad
Notez que la valeur par défaut pour la génération du fichier de symboles est Breakpad. N'utilisez ce drapeau que si vous avez ajouté
symbolGenerator { csym() }
dans votre configuration de build et vous souhaitez le remplacer pour utiliser Breakpad à la place.--dry-run
Génère les fichiers de symboles mais ne les télécharge pas
Cet indicateur est utile si vous souhaitez inspecter le contenu des fichiers envoyés.
--debug
Fournit des informations de débogage supplémentaires Enfin, forcez un crash de test pour terminer la configuration de Crashlytics et voir les données initiales dans le tableau de bord Crashlytics de la console Firebase.
Après avoir créé votre application dans le cadre d'un crash forcé, assurez-vous d'exécuter la commande
crashlytics:symbols:upload
CLI Firebase pour télécharger votre fichier de symboles.