Personnalisez vos rapports d'erreur Firebase Crashlytics

iOS+ Android Flutter Unity

Dans le tableau de bord Crashlytics, vous pouvez cliquer sur un problème et obtenir un rapport d'événement détaillé. Vous pouvez personnaliser ces rapports pour vous aider à mieux comprendre ce qui se passe dans votre application et les circonstances entourant les événements signalés à Crashlytics.

• Signalez les exceptions non interceptées et les exceptions interceptées à Crashlytics.

• Instrumentez votre application pour enregistrer les clés personnalisées , les messages de journal personnalisés et les identifiants utilisateur .

• Obtenez automatiquement les journaux de fil d'Ariane si votre application utilise le SDK Firebase pour Google Analytics. Ces journaux vous donnent une visibilité sur les actions des utilisateurs menant à un événement collecté par Crashlytics dans votre application.

• Désactivez les rapports automatiques d'incidents et activez les rapports d'adhésion pour vos utilisateurs. Notez que, par défaut, Crashlytics collecte automatiquement les rapports de plantage natifs de la plateforme pour tous les utilisateurs de votre application.

Remarque : Pour les applications Flutter, les rapports fatals sont envoyés à Crashlytics en temps réel sans que l'utilisateur ait besoin de redémarrer l'application. Les rapports non fatals sont écrits sur le disque pour être envoyés avec le prochain rapport fatal ou au redémarrage de l'application.

Signaler les exceptions non interceptées

Vous pouvez automatiquement détecter toutes les erreurs « fatales » générées dans le framework Flutter en remplaçant FlutterError.onError par FirebaseCrashlytics.instance.recordFlutterFatalError . Alternativement, pour intercepter également les exceptions « non fatales », remplacez FlutterError.onError par FirebaseCrashlytics.instance.recordFlutterError :

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

Erreurs asynchrones

Les erreurs asynchrones ne sont pas détectées par le framework Flutter :

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

Pour détecter de telles erreurs, vous pouvez utiliser le gestionnaire PlatformDispatcher.instance.onError :

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

Erreurs en dehors de Flutter

Pour détecter les erreurs qui se produisent en dehors du contexte Flutter, installez un écouteur d'erreurs sur le Isolate actuel :

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

Signaler les exceptions détectées

En plus de signaler automatiquement les plantages de votre application, Crashlytics vous permet d'enregistrer des exceptions non fatales et de vous les envoyer la prochaine fois qu'un événement fatal est signalé ou au redémarrage de l'application.

Remarque : Crashlytics stocke uniquement les huit exceptions non fatales enregistrées les plus récentes. Si votre application en génère plus de huit, les anciennes exceptions sont perdues. Ce décompte est réinitialisé chaque fois qu'une exception fatale est levée, car cela entraîne l'envoi d'un rapport à Crashlytics.

Utilisez la méthode recordError pour enregistrer les exceptions non fatales dans les blocs catch de votre application. Par exemple:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

Vous souhaiterez peut-être également enregistrer des informations supplémentaires sur l'erreur, ce qui est possible en utilisant la propriété information :

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

Avertissement : Si vous souhaitez inclure une valeur unique (par exemple, un ID utilisateur ou un horodatage) dans votre message d'exception, utilisez une clé personnalisée au lieu d'ajouter la valeur directement dans le message d'exception. L'ajout direct de valeurs peut entraîner plusieurs problèmes et amener Crashlytics à limiter les erreurs de rapport dans votre application.

Ces exceptions apparaissent comme des problèmes non fatals dans la console Firebase. Le résumé du problème contient toutes les informations d'état que vous obtenez normalement en cas de panne, ainsi que les répartitions par version et périphérique matériel.

Crashlytics traite les exceptions sur un thread d'arrière-plan dédié pour minimiser l'impact sur les performances de votre application. Pour réduire le trafic réseau de vos utilisateurs, Crashlytics limitera le nombre de rapports envoyés depuis l'appareil, si nécessaire.

Ajouter des clés personnalisées

Les clés personnalisées vous aident à obtenir l'état spécifique de votre application menant à un crash. Vous pouvez associer des paires clé/valeur arbitraires à vos rapports d'erreur, puis utiliser les clés personnalisées pour rechercher et filtrer les rapports d'erreur dans la console Firebase.

• Dans le tableau de bord Crashlytics , vous pouvez rechercher les problèmes correspondant à une clé personnalisée.

• Lorsque vous examinez un problème spécifique dans la console, vous pouvez afficher les clés personnalisées associées à chaque événement (sous-onglet Clés ) et même filtrer les événements par clés personnalisées (menu Filtrer en haut de la page).

Remarque : Crashlytics prend en charge un maximum de 64 paires clé/valeur. Une fois ce seuil atteint, les valeurs supplémentaires ne sont pas enregistrées. Chaque paire clé/valeur peut atteindre 1 Ko.

Utilisez la méthode d'instance setCustomKey pour définir des paires clé/valeur. Voici quelques exemples:

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);

Ajouter des messages de journal personnalisés

Pour vous donner plus de contexte sur les événements ayant conduit à un crash, vous pouvez ajouter des journaux Crashlytics personnalisés à votre application. Crashlytics associe les journaux à vos données de crash et les affiche dans la console Firebase , sous l'onglet Journaux Crashlytics.

Remarque : Pour éviter de ralentir votre application, Crashlytics limite les journaux à 64 Ko et supprime les anciennes entrées de journal lorsque les journaux d'une session dépassent cette limite.

Utilisez log pour vous aider à identifier les problèmes. Par exemple:

FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");

Définir les identifiants des utilisateurs

Pour diagnostiquer un problème, il est souvent utile de savoir lequel de vos utilisateurs a rencontré un crash donné. Crashlytics inclut un moyen d'identifier de manière anonyme les utilisateurs dans vos rapports d'erreur.

Pour ajouter des ID utilisateur à vos rapports, attribuez à chaque utilisateur un identifiant unique sous la forme d'un numéro d'identification, d'un jeton ou d'une valeur hachée :

FirebaseCrashlytics.instance.setUserIdentifier("12345");

Si jamais vous devez effacer un identifiant utilisateur après l'avoir défini, réinitialisez la valeur sur une chaîne vide. La suppression d'un identifiant utilisateur ne supprime pas les enregistrements Crashlytics existants. Si vous devez supprimer des enregistrements associés à un ID utilisateur, contactez l'assistance Firebase .

Obtenir les journaux de fil d'Ariane

Les journaux de fil d'Ariane vous permettent de mieux comprendre les interactions qu'un utilisateur a eues avec votre application ayant conduit à un crash, un événement non fatal ou ANR. Ces journaux peuvent être utiles lorsque vous essayez de reproduire et de déboguer un problème.

Les journaux de fil d'Ariane sont alimentés par Google Analytics. Par conséquent, pour obtenir des journaux de fil d'Ariane, vous devez activer Google Analytics pour votre projet Firebase et ajouter le SDK Firebase pour Google Analytics à votre application. Une fois ces conditions remplies, les journaux de fil d'Ariane sont automatiquement inclus avec les données d'un événement dans l'onglet Journaux lorsque vous affichez les détails d'un problème.

Le SDK Analytics enregistre automatiquement l'événement screen_view , ce qui permet aux journaux de fil d'Ariane d'afficher une liste des écrans consultés avant l'événement crash, non fatal ou ANR. Un journal de fil d'Ariane screen_view contient un paramètre firebase_screen_class .

Les journaux de fil d'Ariane contiennent également tous les événements personnalisés que vous enregistrez manuellement dans la session de l'utilisateur, y compris les données de paramètres de l'événement. Ces données peuvent aider à montrer une série d'actions de l'utilisateur menant à un crash, un événement non fatal ou ANR.

Notez que vous pouvez contrôler la collecte et l'utilisation des données Google Analytics , qui incluent les données qui alimentent les journaux de fil d'Ariane.

Activer les rapports d'adhésion

Par défaut, Crashlytics collecte automatiquement les rapports d'erreur pour tous les utilisateurs de votre application. Pour donner aux utilisateurs plus de contrôle sur les données qu'ils envoient, vous pouvez activer les rapports opt-in en désactivant les rapports automatiques et en envoyant les données à Crashlytics uniquement lorsque vous le souhaitez dans votre code :

1. Désactivez nativement la collecte automatique :

   Plateformes Apple

   Ajoutez une nouvelle clé à votre fichier Info.plist :

   • Clé : FirebaseCrashlyticsCollectionEnabled
   • Valeur : false

   Android

   Dans le bloc application de votre fichier AndroidManifest.xml , ajoutez une balise meta-data pour désactiver la collecte automatique :

   <meta-data
       android:name="firebase_crashlytics_collection_enabled"
       android:value="false" />
   

2. Activez la collecte pour certains utilisateurs en appelant le remplacement de la collecte de données Crashlytics au moment de l'exécution.

   La valeur de remplacement persiste lors des lancements de votre application afin que Crashlytics puisse collecter automatiquement des rapports. Pour désactiver le rapport automatique d'incidents, transmettez false comme valeur de remplacement. Lorsqu'elle est définie sur false , la nouvelle valeur ne s'applique pas jusqu'à la prochaine exécution de l'application.

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

Remarque : Lorsque la collecte de données est désactivée, Crashlytics stocke les informations sur les crashs localement sur l'appareil. Si la collecte de données est ensuite activée, toutes les informations de crash stockées sur l'appareil seront envoyées à Crashlytics pour traitement.

Gérer les données Crash Insights

Crash Insights vous aide à résoudre les problèmes en comparant vos traces de pile anonymisées aux traces d'autres applications Firebase et en vous indiquant si votre problème fait partie d'une tendance plus large. Pour de nombreux problèmes, Crash Insights fournit même des ressources pour vous aider à déboguer le crash.

Crash Insights utilise des données d'accident agrégées pour identifier les tendances courantes en matière de stabilité. Si vous préférez ne pas partager les données de votre application, vous pouvez désactiver Crash Insights dans le menu Crash Insights en haut de votre liste de problèmes Crashlytics dans la console Firebase .

Remarque : La désactivation du partage de données supprime également les informations sur vos problèmes. Les modifications peuvent prendre jusqu'à 24 heures pour prendre effet.