Flutter SDK

FlutterAndroidiOS

The Snapbug Flutter SDK provides a Dart bridge to the native Snapbug SDK, enabling network inspection, analytics monitoring, crash reporting, and live logs from your Flutter app on Android and iOS.

Requirements

Flutter >= 3.3.0
Dart >= 3.5.4
Dio >= 5.0.0 (for automatic network interception)
Android minSdk 23
iOS: Apple-silicon simulators or physical devices (the bundled XCFramework excludes x86_64 simulator slices)

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  snapbug_flutter: ^0.1.1

Then run:

flutter pub get

The native SDK is resolved for you: Android pulls ai.snapbug:snapbug from Maven Central, iOS pulls the Snapbug pod from CocoaPods trunk (run pod install as usual after adding the plugin).

Release builds on iOS

On Android the release twin is wired in automatically. CocoaPods has no equivalent mechanism, so add two lines to your app's ios/Podfile:

# inside target 'Runner'
pod 'Snapbug',       '~> 0.1.1', :configurations => ['Debug']
pod 'Snapbug-no-op', '~> 0.1.1', :configurations => ['Release']

Snapbug-no-op exposes the same API with every call inert. The plugin compiles against it unchanged, and your App Store build carries neither the inspector nor the overlay — Snapbug.framework drops from 31 MB to 6.7 MB, while Debug keeps the live SDK. See iOS SDK → Release builds.

Quick Start

No native code required. Snapbug.start() from Dart boots the native SDK through the plugin — nothing goes in MainActivity or AppDelegate.

import 'dart:async';
import 'package:snapbug_flutter/snapbug_flutter.dart';
 
void main() {
  runZonedGuarded(() async {
    WidgetsFlutterBinding.ensureInitialized();
 
    await Snapbug.start();
 
    runApp(const MyApp());
  }, (error, stack) {
    SnapbugCrashReporter.reportError(error, stack);
  }, zoneSpecification: SnapbugLogs.zoneSpecification());
}

All Dart plugins are enabled by default; pass plugins: [...] to Snapbug.start() to enable a subset. Settings go through the same call:

await Snapbug.start(
  serverHost: '192.168.1.42',   // LAN IP of your Mac for physical devices; not needed for simulators or relay
  overlay: 'BUBBLE',            // Android only: BUBBLE (default), FAB or NONE
  appVersion: '1.0.0',
);

If you start the native SDK yourself

Only needed when you want native configuration with no Dart equivalent — declaring your app's own deep links, for instance. Snapbug.start() then sees the running SDK and just attaches the Dart plugins to the bridge.

The plugin declares the SDK as implementation, so the classes exist at runtime but are not on your app's compile classpath. For your own call, add exactly this pair to android/app/build.gradle:

dependencies {
    debugImplementation("ai.snapbug:snapbug:0.1.1")
    releaseImplementation("ai.snapbug:snapbug-no-op:0.1.1")
}

Both artifacts expose every plugin through api. Do not add the per-plugin artifacts (snapbug-analytics, snapbug-device, snapbug-transport-webrtc-no-op, …) — in release they land next to their no-op twins and the build fails on Duplicate class.

Snapbug.start takes an Activity, which it needs for the overlay, so this does not go in Application:

import io.snapbug.sdk.OverlayMode
import io.snapbug.sdk.Snapbug
 
class MainActivity : FlutterActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Snapbug.start(this) {
            overlay = OverlayMode.BUBBLE
            deeplinks { deeplink("myapp://product", label = "Open product") }
        }
    }
}

Logs

Log lines stream into the Logs inspector in real time:

Android — the native SDK captures logcat; Dart print/debugPrint land there under the flutter tag, so nothing extra is needed.
iOS — the Flutter engine routes Dart output to os_log, past stdout, so the Dart SnapbugLogs plugin forwards it itself: debugPrint (including Flutter framework error dumps with stack traces) is hooked automatically by Snapbug.start(); plain print() is captured through SnapbugLogs.zoneSpecification() passed to runZonedGuarded as shown above.

Network Inspection

With Dio

Add the SnapbugDioInterceptor to your Dio client:

import 'package:dio/dio.dart';
import 'package:snapbug_flutter/snapbug_flutter.dart';
 
final dio = Dio();
dio.interceptors.add(SnapbugDioInterceptor());

All HTTP requests made through this Dio instance appear in the network inspector.

Manual Logging

For HTTP clients other than Dio, log requests and responses manually. Generate a call ID first so the request and response are linked:

final network = Snapbug.getPlugin<SnapbugNetwork>()!;
final callId = network.generateCallId();
 
network.logRequest(
  callId: callId,
  url: 'https://api.example.com/users',
  method: 'GET',
  headers: {'Authorization': 'Bearer token'},
);
 
network.logResponse(
  callId: callId,
  durationMs: 150,
  statusCode: 200,
  contentType: 'application/json',
  headers: {'content-type': 'application/json'},
  body: '{"users": []}',
);

Analytics

Log analytics events with a source identifier:

Snapbug.analytics('firebase').logEvents([
  AnalyticsEvent('screen_view', properties: {'screen_name': 'Home'}),
  AnalyticsEvent('button_click', properties: {'button_id': 'sign_up'}),
]);

You can use any string as the source identifier to group events (e.g., firebase, amplitude, mixpanel).

Crash Reporter

Automatic Fatal Error Capture

Enable fatal error capture when starting the SDK, and wrap your entry point in runZonedGuarded:

void main() {
  runZonedGuarded(() async {
    WidgetsFlutterBinding.ensureInitialized();
 
    await Snapbug.start(
      plugins: [SnapbugCrashReporter(catchFatalErrors: true)],
    );
 
    runApp(const MyApp());
  }, (error, stack) {
    SnapbugCrashReporter.reportError(error, stack);
  });
}

Manual Error Reporting

Report caught exceptions manually:

try {
  await riskyOperation();
} catch (error, stackTrace) {
  SnapbugCrashReporter.reportError(error, stackTrace);
}

Architecture

The Flutter SDK follows a bridge architecture:

Flutter (Dart)
    |
    v
Platform Channel (Method Channel)
    |
    v
Native Snapbug SDK (Android / iOS)
    |
    v
WebSocket / WebRTC --> Snapbug inspector

Dart calls are forwarded to the native Snapbug SDK, which owns the connection to the inspector (Chrome Extension room-code flow or local network).

Example App

A complete Flutter example app is available at SnapbugFlutter/example/ in the repository.

To run it:

cd SnapbugFlutter/example
flutter run

To build for a platform explicitly:

flutter build apk --debug          # Android
flutter build ios --simulator      # iOS (Apple-silicon simulator)

Next Steps

Connect your device
Troubleshooting for common issues

iOS React Native