Obtenez des rapports de plantage Android NDK

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

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

  2. Recommandé : pour obtenir automatiquement des journaux de fil d'Ariane afin de comprendre les actions des utilisateurs ayant conduit à un crash, un événement non fatal ou ANR, 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 > Paramètres du projet dans la console Firebase.

    • 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.7.2"))

    // 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.2")
    implementation("com.google.firebase:firebase-analytics:21.5.1")
}
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 s'appuyer sur le module de bibliothèque principal (pour plus de détails, consultez la FAQ sur cette initiative ).

Étape 2 : Ajoutez le plugin Crashlytics Gradle à votre application

  1. 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 bloc plugins :

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

  1. Afin que vous puissiez accéder à la tâche de téléchargement automatisé de symboles, assurez-vous que nativeSymbolUploadEnabled est défini sur true dans le fichier Gradle de votre module (au niveau de l'application).

  2. 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
    
  3. 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.

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

  3. Forcez le crash du test afin d'envoyer le premier rapport de crash de votre application :

    1. Ouvrez votre application à partir de votre appareil de test ou de votre émulateur.

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

    3. Après le crash de votre application, redémarrez-la afin qu'elle puisse envoyer le rapport de crash à Firebase.

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

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