Recevoir des rapports d'erreur du NDK Android

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

Ce guide explique comment configurer le signalement des plantages avec le SDK Firebase Crashlytics pour le NDK.

Si vous souhaitez apprendre à utiliser Crashlytics dans vos projets Unity, consultez le guide de démarrage Unity.

Avant de commencer

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

2. Recommandé : Pour obtenir automatiquement des journaux de repères afin de comprendre les actions des utilisateurs ayant conduit à un plantage, un problème non fatal ou un événement ANR, vous devez activer Google Analytics dans votre projet Firebase.

   • Si Google Analytics n'est pas activé dans votre projet Firebase existant, vous pouvez l'activer dans l'onglet Integrations (Intégrations) de  > Project settings (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 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 votre fichier Gradle de 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 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:33.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")
}

Si vous utilisez Firebase Android BoM, votre application utilisera toujours des versions compatibles des bibliothèques Firebase Android.

(Alternative) Ajoutez des dépendances de la bibliothèque Firebase sans utiliser la classe 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, nous vous recommandons vivement 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.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}

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 le plug-in Gradle Crashlytics au bloc plugins :

   Kotlin

   Utilisez-vous toujours la syntaxe buildscript ? 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 la syntaxe buildscript ? 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 : Ajouter 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 toutes les architectures compatibles avec le NDK Android. Si votre application cible un sous-ensemble spécifique, vous pouvez utiliser des fractionnements ABI pour exclure les architectures inutiles.

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

Pour générer des traces de pile lisibles à partir des plantages du NDK, Crashlytics doit connaître les symboles de vos binaires natifs. Le plug-in Gradle Crashlytics inclut la tâche uploadCrashlyticsSymbolFileBUILD_VARIANT pour automatiser ce processus.

Remarque :Crashlytics accepte d'autres options pour importer des symboles, en fonction de la configuration et des outils de votre application, comme 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 fichier Gradle de module (au niveau de l'application).

2. Pour que les noms de méthode apparaissent dans vos traces de pile, vous devez appeler explicitement la tâche uploadCrashlyticsSymbolFileBUILD_VARIANT après chaque compilation de votre bibliothèque NDK. Exemple :

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT

3. Le SDK Crashlytics pour NDK et le plug-in Gradle Crashlytics 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 ID en exécutant readelf -n sur chaque binaire. Si l'ID de compilation est absent, ajoutez -Wl,--build-id aux indicateurs de votre système de compilation pour résoudre le problème.

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

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

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, lorsqu'il est enfoncé, provoque un plantage. Le bouton est intitulé "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 de test afin d'envoyer le premier rapport de plantage 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. Une fois que votre application plante, redémarrez-la pour qu'elle puisse envoyer le rapport d'erreur à Firebase.

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

   Si vous avez actualisé la console et que le plantage du test ne s'affiche toujours pas au bout de cinq minutes, activez la journalisation de débogage pour voir si votre application envoie des rapports de plantage.

Et voilà ! Crashlytics surveille désormais les plantages de votre application. Vous pouvez consulter et examiner les rapports et les statistiques sur les plantages 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 collectant des 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 des failles de sécurité des applications. Pour profiter de cette fonctionnalité de débogage, assurez-vous que votre application a GWP-ASan explicitement activé et qu'elle utilise la dernière version du SDK Crashlytics pour le NDK (version 18.3.6 ou ultérieure ou Firebase BoM 31.3.0 ou version ultérieure).

• 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 d'erreur de votre application Android par trace Google Play directement dans le tableau de bord Crashlytics. Vous pouvez ainsi mieux cibler 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 s'applique aux builds Gradle standards. Cependant, certaines applications utilisent une configuration ou des outils différents (par exemple, un processus de compilation autre que Gradle). Dans ces situations, les options suivantes peuvent vous aider à 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 créées dans un module de bibliothèque/de fonctionnalité ou fournies par un tiers
• Si la tâche d'importation automatique des symboles échoue ou si 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 la propriété unstrippedNativeLibsDir dans l'extension Crashlytics de votre fichier de compilation Gradle.

1. Assurez-vous d'avoir effectué les tâches initiales suivantes du workflow principal plus tôt sur cette page :

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

   2. Ajout du SDK Crashlytics pour NDK et du plug-in Gradle Crashlytics.

   3. Ajoutez l'extension Crashlytics à votre build.

   4. Configurez l'importation automatique de symboles natifs.

2. Pour que la tâche d'importation automatique des symboles puisse trouver vos informations sur les symboles, ajoutez les éléments suivants à votre fichier Gradle de 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 dans le répertoire spécifié des 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 une même version en fournissant une liste ou une instance FileCollection

   • (À partir de la version 3.0.0 du plug-in Gradle Crashlytics) Accumulez plusieurs répertoires dans des produits et des types de compilation individuels.

   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'importe que les symboles dans MY/NATIVE/LIBS, mais uploadCrashlyticsSymbolFilesFeatureXRelease importera les symboles dans 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 les builds autres que Gradle ou les bibliothèques natives non supprimées inaccessibles

Cette option peut s'avérer 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 d'exécuter une commande CLI Firebase lorsque vous créez un build ou toute build pour lequel vous souhaitez afficher des traces de pile décodées dans la console Firebase.

1. Assurez-vous d'avoir effectué les tâches initiales suivantes du workflow principal plus tôt sur cette page :

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

   2. Ajout du SDK Crashlytics pour le NDK et du plug-in Gradle Crashlytics.

   Notez qu'avec cette option, vous n'avez pas besoin d'ajouter l'extension firebaseCrashlytics ni de configurer l'importation automatique de symboles, car vous devrez utiliser la CLI Firebase (voir les étapes ci-dessous) pour générer et importer vos fichiers de symboles.

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, veillez à passer à la dernière version.

   2. (uniquement pour les applications utilisant le niveau d'API Android 30 ou version ultérieure) Mettez à jour le modèle AndroidManifest.xml de votre application pour désactiver le taggage 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é dans Assets/Plugins/Android/AndroidManifest.xml.

      3. Ajoutez l'attribut suivant à la balise 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 étape chaque fois que vous créez un build ou un build pour lequel vous souhaitez afficher des traces de pile symbolisées dans la console Firebase.

   Une fois la compilation terminée, générez un fichier de symboles compatible avec Crashlytics et importez-le sur les serveurs Firebase en exécutant la commande CLI Firebase suivante :

   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 trouver votre ID d'application Firebase ?

     Vous pouvez trouver votre ID d'application Firebase de deux manières :

     • Dans votre fichier google-services.json, votre ID d'application est la valeur mobilesdk_app_id ; ou

     • Dans la console Firebase, accédez aux paramètres du projet. Faites défiler la page jusqu'à la fiche Vos applications, puis cliquez sur l'application Firebase souhaitée pour trouver son ID d'application.

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

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

     • Vous avez créé l'APK directement depuis Unity. PATH/TO/SYMBOLS est le chemin d'accès du 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 permettant d'utiliser la 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 du générateur Breakpad par défaut Non recommandé. 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 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() } à votre configuration de compilation et que vous souhaitez le remplacer pour utiliser 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 de test pour terminer la configuration de Crashlytics et afficher les données initiales dans le tableau de bord Crashlytics de la console Firebase.

   Après avoir compilé votre application pour forcer un plantage, veillez à exécuter la commande Firebase CLI crashlytics:symbols:upload pour importer votre fichier de symboles.

---