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

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

É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.

  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

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