Flutter

Flutter plugin - Dart error capture bridged over a MethodChannel into the native Android/iOS BugWatch SDKs: native crashes, ANRs/hangs, sessions, breadcrumbs and the offline queue come with it.

Requirementslink

• Dart 3.11+ · Flutter 3.3+ · iOS 14+ · Android minSdk 24
• The plugin pins compatible native SDK versions - no separate native install needed

1 - Installlink

flutter pub add bugwatch

2 - Initialise (before runApp)link

import 'package:bugwatch/bugwatch.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await BugWatch.instance.init(const BugWatchOptions(
    projectId: String.fromEnvironment('BUGWATCH_PROJECT_ID'),
    appSecret: String.fromEnvironment('BUGWATCH_APP_SECRET'),
    environment: 'production',
    release: '1.4.2+318',
  ));
  runApp(const MyApp());
}

Pass credentials with --dart-define (or --dart-define-from-file) so they stay out of source.

3 - Configuration optionslink

autoCaptureErrors (true) · sampleRate (1.0) · sensitiveFields · batchSize 50 · flushIntervalMs 5000 · maxQueueSize 1000 · retry (3 attempts, 500 ms → 10 s) · debug · onDiagnostic stream for SDK self-reporting.

4 - Capture APIlink

BugWatch.instance.captureException(error, stackTrace: st);
BugWatch.instance.captureMessage('Sync finished', level: 'info');
BugWatch.instance.setUser(BugWatchUser(id: 'u_123', email: 'ada@example.com'));
BugWatch.instance.setTag('tenant', 'acme');
BugWatch.instance.setContext('payment', {'provider': 'paystack'});
BugWatch.instance.addBreadcrumb('Tapped checkout');
await BugWatch.instance.flush();

For code outside the Flutter zone, wrap with BugWatch.instance.runZonedGuarded(() => …).

Automatic capturelink

• Dart errors - FlutterError.onError and PlatformDispatcher.onError are hooked with your existing handlers chained.
• Native side - platform crashes (incl. Android NDK), ANRs/hangs, sessions, breadcrumbs and offline persistence come from the underlying native SDKs with the same credentials.

5 - Symbolication (CI)link

Obfuscated release builds need the Dart symbols uploaded per release:

flutter build apk --release --obfuscate --split-debug-info=build/symbols
npx @newinstance/bugwatch-cli artifacts upload build/symbols \
  --release "1.4.2+318" --platform flutter --type dart-symbols --token "$BUGWATCH_CI_KEY"

Add the Android R8 mapping / iOS dSYMs for native frames (see the Android and iOS & macOS pages).

Troubleshootinglink

• MissingPluginException → hot-restart after adding the plugin doesn't register native code - full rebuild (flutter run from cold).
• Dart stacks unreadable in release → build ran without --split-debug-info, or the uploaded release string differs from init.release.
• Nothing sends in debug on iOS simulator → check debug: true diagnostics; simulator clock skew still applies to the HMAC token.

The request below is the exact wire call for a Dart error delivered through the native bridge.