Personnaliser les rapports d'erreur pour Flutter

Sélectionnez la plate-forme :

iOS+ Android Flutter Unity

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

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

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

• Obtenez automatiquement des journaux de navigation si votre application utilise le SDK Firebase pour Google Analytics. Ces journaux vous donnent une visibilité sur les actions de l'utilisateur ayant conduit à un événement collecté par Crashlyticsdans votre application.

• Désactivez le signalement automatique des plantages et activez le signalement sur activation pour vos utilisateurs. Notez que, par défaut, Crashlytics collecte automatiquement les rapports de plantage natifs de la plate-forme pour tous les utilisateurs de votre application.

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

Signaler des exceptions

Signaler des exceptions non interceptées

Vous pouvez intercepter automatiquement toutes les erreurs "fatales" générées dans le framework Flutter en remplaçant FlutterError.onError par FirebaseCrashlytics.instance.recordFlutterFatalError. Vous pouvez également intercepter les exceptions "non fatales" en remplaçant 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 interceptées par le framework Flutter :

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

Pour intercepter ces 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 intercepter les erreurs qui se produisent en dehors du contexte Flutter, installez un écouteur d'erreurs sur l'élément 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 des exceptions interceptées

En plus de signaler automatiquement les plantages de votre application, Crashlytics vous permet d'enregistrer les exceptions non fatales et de vous les envoyer lors du prochain événement fatal ou lorsque l'application redémarre.

Remarque : Crashlytics ne stocke que les huit exceptions non fatales enregistrées les plus récentes. Si votre application en génère plus de huit, les exceptions plus anciennes sont perdues. Ce nombre est réinitialisé chaque fois qu'une exception fatale est généré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. Exemple :

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

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

Vous pouvez également enregistrer d'autres informations sur l'erreur à l'aide de 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 code temporel) 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 peut amener Crashlytics à limiter le signalement des erreurs dans votre application.

Ces exceptions apparaissent comme des problèmes non fatals dans la Firebase console. Le résumé du problème contient toutes les informations d'état que vous obtenez normalement des plantages, ainsi que des répartitions par version et par appareil.

Crashlytics traite les exceptions sur un thread d'arrière-plan dédié afin de 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 hors de l'appareil, si nécessaire.

Ajouter des clés personnalisées

Les clés personnalisées vous permettent de connaître l'état spécifique de votre application pouvant entraîner un plantage. Vous pouvez associer des paires clé/valeur arbitraires à vos rapports de plantage, puis utiliser les clés personnalisées pour rechercher et filtrer les rapports de plantage dans la Firebase console.

• Dans le Crashlytics tableau de bord, vous pouvez rechercher les problèmes qui correspondent à 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 accepte 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 avoir une taille maximale de 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 obtenir plus de contexte sur les événements ayant conduit à un plantage, vous pouvez ajouter des journaux Crashlytics personnalisés à votre application. Crashlytics associe les journaux à vos données de plantage et les affiche dans la Firebase console, sous l'onglet Crashlytics Journaux.

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

Utilisez log pour identifier les problèmes. Exemple :

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

Définir des identifiants utilisateur

Pour diagnostiquer un problème, il est souvent utile de savoir quels utilisateurs ont rencontré un plantage donné. Crashlytics inclut un moyen d'identifier anonymement les utilisateurs dans vos rapports de plantage.

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

Obtenir des journaux de navigation

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

Les journaux de navigation sont alimentés par Google Analytics. Pour les obtenir, 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 navigation sont automatiquement inclus dans les données d'un événement sous 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 navigation d'afficher la liste des écrans consultés avant le plantage, le problème non fatal ou l'événement ANR. Un journal de navigation screen_view contient un paramètre firebase_screen_class.

Les journaux de navigation sont également renseignés avec tous les événements personnalisés que vous enregistrez manuellement dans la session de l'utilisateur, y compris les données de paramètre de l'événement. Ces données peuvent montrer une série d'actions de l'utilisateur ayant conduit à un plantage, un problème non fatal ou un événement ANR.

Notez que vous pouvez contrôler la collecte et l'utilisation des donnéesGoogle Analytics, y compris celles qui alimentent les journaux de navigation.

Activer le signalement sur activation

Si vous activez le signalement sur activation en désactivant le signalement automatique, vous réduirez la précision du nombre d’événements et des métriques sans plantage de votre application, ce qui les rendra moins représentatifs de la stabilité globale de votre application. En savoir plus.

Par défaut, Crashlytics collecte automatiquement les rapports de plantage 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 le signalement sur activation en désactivant le signalement automatique et en n'envoyant des données à Crashlytics que lorsque vous le choisissez dans votre code.

1. Désactivez la collecte automatique de manière native :

   Plates-formes Apple

   Ajoutez une clé à votre fichier Info.plist :

   • Clé : FirebaseCrashlyticsCollectionEnabled
   • Valeur : false

   Android

   Dans le bloc application de votre fichier AndroidManifest.xml, ajoutez un tag 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 Crashlytics remplacement de la collecte de données au moment de l'exécution. La valeur de remplacement persiste lors de tous les lancements ultérieurs de votre application. Crashlytics peut ainsi collecter automatiquement des rapports pour cet utilisateur.

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

   Si l'utilisateur désactive ultérieurement la collecte de données, vous pouvez transmettre false comme valeur de remplacement. Cette valeur s'appliquera lors du prochain lancement de l'application par l'utilisateur et persistera lors de tous les lancements ultérieurs pour cet utilisateur.

Remarque : Lorsque la collecte de données est désactivée pour un utilisateur, Crashlytics stocke les informations sur les plantages localement sur l’appareil. Si la collecte de données est activée par la suite, toutes les informations sur les plantages 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 à celles 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 plantage.

Crash Insights utilise des données de plantage agrégées pour identifier les tendances de stabilité courantes. 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** : En désactivant le partage de données, vous supprimerez les insights sur vos problèmes. L'application des modifications peut prendre jusqu'à 24 heures.

Étapes suivantes

• Exportez vos données vers BigQuery ou Cloud Logging pour bénéficier d'analyses et de fonctionnalités avancées, comme l'interrogation de vos données, la création de tableaux de bord personnalisés et la configuration d'alertes personnalisées.