Personnaliser vos rapports d'erreur Firebase Crashlytics

iOS+ Android Flutter Unity

Dans le tableau de bord Crashlytics, vous pouvez cliquer sur un problème pour obtenir un rapport détaillé sur l'événement. Vous pouvez personnaliser ces rapports pour 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 des clés personnalisées, des messages de journal personnalisés et des identifiants utilisateur.

• Obtenez automatiquement des journaux de fil d'Ariane si votre application utilise le SDK Firebase pour Google Analytics. Ces journaux vous permettent de voir les actions des utilisateurs qui ont précédé un événement collecté par Crashlytics dans votre application.

• Désactivez la création automatique de rapports d'erreur et activez les rapports nécessitant une confirmation pour vos utilisateurs. Notez que, par défaut, Crashlytics collecte automatiquement les rapports d'erreur natifs de la plate-forme 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 lorsque l'application redémarre.

Signaler les exceptions non détecté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. 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 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 détecter les erreurs qui se produisent en dehors du contexte Flutter, installez un écouteur d'erreur sur l'Isolate actuelle:

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 intercepté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 lorsque l'application redémarre.

Remarque :Crashlytics ne stocke que les huit exceptions non fatales enregistrées les plus récentes. Si votre application génère plus de huit exceptions, les plus anciennes sont perdues. Ce nombre est réinitialisé chaque fois qu'une exception fatale est générée, car un rapport est envoyé à Crashlytics.

Utilisez la méthode recordError pour enregistrer les exceptions non fatales dans les blocs de capture 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 consigner d'autres informations sur l'erreur, ce qui est possible à 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. Ajouter des valeurs directement peut entraîner plusieurs problèmes et Crashlytics peut limiter les erreurs de création de rapports dans votre application.

Ces exceptions s'affichent sous forme de 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 plantage, ainsi que des répartitions par version et par appareil matériel.

Crashlytics traite les exceptions sur un thread en 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 limite le nombre de rapports envoyés depuis 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 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 accepte un maximum de 64 paires clé/valeur. Une fois ce seuil atteint, aucune valeur supplémentaire n'est enregistrée. 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 qui ont 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 console Firebase, sous l'onglet Crashlytics Journaux.

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 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 quel utilisateur a rencontré un plantage donné. Crashlytics permet 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'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. Effacer un ID 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 des fils d'Ariane

Les journaux de breadcrumb vous permettent de mieux comprendre les interactions d'un utilisateur avec votre application avant un plantage, un problème non fatal ou un événement ANR. Ces journaux peuvent être utiles pour essayer de reproduire et de déboguer un problème.

Les journaux de fil d'Ariane 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 fil d'Ariane sont automatiquement inclus avec les données d'un événement dans l'onglet Journaux lorsque vous consultez les détails d'un problème.

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

Les journaux de fil d'Ariane sont également renseignés par 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 aider à afficher une série d'actions 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ées Google Analytics, y compris les données qui renseignent les journaux de fil d'Ariane.

Activer les rapports nécessitant une confirmation

Par défaut, Crashlytics collecte automatiquement les rapports d'erreur pour tous les utilisateurs de votre application. Pour permettre aux utilisateurs de mieux contrôler les données qu'ils envoient, vous pouvez activer les rapports nécessitant une confirmation en désactivant les rapports automatiques et en n'envoyant des données à Crashlytics que lorsque vous le souhaitez dans votre code:

1. Désactiver 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 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 forçage de la collecte de données Crashlytics au moment de l'exécution.

   La valeur de forçage persiste à chaque lancement de votre application afin que Crashlytics puisse collecter automatiquement des rapports. Pour désactiver la création automatique de rapports d'erreur, transmettez false comme valeur de remplacement. Lorsque cette valeur est définie sur false, la nouvelle valeur ne s'applique qu'à l'exécution suivante de l'application.

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

Remarque: Si vous désactivez la création automatique de rapports, tenez compte des points suivants :

• 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 sont envoyées à Crashlytics pour traitement.
• Lorsque vous activez les rapports nécessitant une acceptation, les informations sur les plantages ne peuvent être collectées que auprès des utilisateurs qui ont explicitement accepté la collecte de données. Par conséquent, la précision des métriques sans plantage (comme les utilisateurs et les sessions sans plantage) sera affectée, car Crashlytics ne dispose que des informations sur les plantages de ces utilisateurs ayant activé la fonctionnalité (plutôt que de tous vos utilisateurs). Cela signifie que vos métriques sans plantage peuvent être moins fiables et moins représentatives de la stabilité globale de votre application.

Gérer les données des insights sur les plantages

Les insights sur les plantages vous aident à 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 la liste des problèmes Crashlytics dans la console Firebase.

Remarque :En désactivant le partage de données, vous supprimerez les insights sur vos problèmes. La prise en compte des modifications peut prendre jusqu'à 24 heures.