firebase-crashlytics

Firebase Crashlytics スキル

このスキルでは、Flutter アプリケーションで Firebase Crashlytics を正しく使用する方法を説明します。

使用するタイミング

次の場合にこのスキルを使用してください。

• Flutter プロジェクトでクラッシュレポートを実装するとき。
• 致命的エラー、非致命的例外、非同期処理／アイソレートのエラーを捕捉するとき。
• キー、ログ、ユーザー識別子を使ってクラッシュレポートをカスタマイズするとき。
• データ収集へのオプトインを設定するとき、またはデバッグビルドでレポートを無効にするとき。
• 難読化されたビルドのシンボルファイルをアップロードするとき。

---

1. セットアップと設定

flutter pub add firebase_crashlytics
flutter pub add firebase_analytics  # enables breadcrumb logs for better crash context

flutterfire configure を実行して Firebase 設定を更新し、Android に必要な Crashlytics Gradle プラグインを追加します。

import 'package:firebase_crashlytics/firebase_crashlytics.dart';

難読化されたコード：

• --split-debug-info や --obfuscate を指定してビルドしたアプリでは、読みやすいスタックトレースを得るためにシンボルファイルをアップロードしてください。
• iOS： Flutter 3.12.0 以降と Crashlytics Flutter プラグイン 3.3.4 以降では、シンボルのアップロードが自動的に処理されます。
• Android： Firebase CLI（v11.9.0 以降）を使用して Flutter のデバッグシンボルをアップロードしてください。

firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

---

2. エラー処理

main() で包括的なエラー捕捉を設定し、すべての発生元からのエラーを捕捉します。

致命的な Flutter エラー：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // Pass all uncaught fatal errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  // Catch async errors not handled by the Flutter framework
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  runApp(MyApp());
}

非致命的な Flutter エラー： recordFlutterFatalError の代わりに recordFlutterError を使用します。

アイソレートのエラー：

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

捕捉した例外（非致命的）：

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

• Crashlytics がセッションごとに保存する非致命的例外は、直近の 8 件のみです。それより古い例外は破棄されます。

---

3. クラッシュレポートのカスタマイズ

カスタムキー（キーと値のペアは最大 64 件、各値は最大 1 kB）：

FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');
FirebaseCrashlytics.instance.setCustomKey('bool_key', true);
FirebaseCrashlytics.instance.setCustomKey('int_key', 1);

カスタムログメッセージ（上限：セッションごとに 64 kB）：

FirebaseCrashlytics.instance.log("User tapped on payment button");

ユーザー識別子：

FirebaseCrashlytics.instance.setUserIdentifier("user-123");
// Clear by setting to blank string
FirebaseCrashlytics.instance.setUserIdentifier("");

• ユーザー ID やタイムスタンプなどの一意な値を例外メッセージに直接含めないでください。代わりにカスタムキーを使用します。

---

4. パフォーマンスと最適化

• Crashlytics はパフォーマンスへの影響を最小限に抑えるため、専用のバックグラウンドスレッドで例外を処理します。
• 致命的なレポートは、アプリの再起動を必要とせず、リアルタイムで送信されます。
• 非致命的なレポートはディスクに書き込まれ、次の致命的なレポートとともに、またはアプリの再起動時に送信されます。
• クラッシュに至るまでのユーザーの操作を把握するには、パンくずログを使用します（Firebase Analytics が必要です）。

デバッグビルドで Crashlytics を無効にする：

if (kReleaseMode) {
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
} else {
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(false);
}

---

5. テストとデバッグ

テストクラッシュを強制的に発生させ、セットアップを確認します。

FirebaseCrashlytics.instance.crash();

確認ワークフロー：

1. リリースモードでアプリをビルドして実行します。
2. テストクラッシュを発生させます。
3. アプリを再度開き、クラッシュレポートをアップロードします。
4. 5 分以内に Firebase Console の Crashlytics ダッシュボードを確認します。
5. カスタムキー、ログ、ユーザー識別子がクラッシュレポートに表示されることを確認します。

• コード難読化を使用する場合は、スタックトレースが適切にシンボル化されていることを確認します。

---

6. オプトインによるレポート

デフォルトでは、Crashlytics はすべてのユーザーのクラッシュレポートを自動的に収集します。

データ収集をユーザーが制御できるようにするには：

• 自動レポートを無効にし、ユーザーがオプトインした場合にのみ setCrashlyticsCollectionEnabled(true) を使って有効にします。
• 上書き値は、その後のすべてのアプリ起動にわたって保持されます。
• ユーザーをオプトアウトさせるには false を渡します。これは次回のアプリ起動から適用されます。
• 無効になっている間、クラッシュ情報はローカルに保存されます。後で有効にすると、ローカルに保存されたクラッシュ情報が Crashlytics に送信されます。

---

参考資料

• Firebase Crashlytics Flutter のドキュメント
• クラッシュレポートをカスタマイズする