Flutter

Start with a direct simulator/emulator connection in Basic mode. No Bonjour setup, access key, or certificate is needed. Flutter uses a plugin, so installation and a native rebuild are still required.

Quick start

Open Tracebeam on your Mac and leave Settings → Connections in Basic mode. Add the SDK checkout to your application’s pubspec.yaml:

dependencies:
  tracebeam_flutter:
    path: /absolute/path/to/tracebeam/tracebeam-flutter

Run flutter pub get. Wrap app startup so supported Dart network traffic, print output, and errors can be observed:

import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:tracebeam_flutter/tracebeam_flutter.dart';

void main() {
  Tracebeam.runGuarded(
    () async {
      WidgetsFlutterBinding.ensureInitialized();
      if (kDebugMode) {
        unawaited(Tracebeam.connect(
          options: const TracebeamConnectOptions(discovery: false),
        ));
      }
      runApp(const App()); // Your application's root widget.
    },
    captureNetwork: true,
    capturePrint: true,
  );
}

Stop and rebuild the app on iOS Simulator or Android Emulator—hot reload/restart cannot install the plugin. Select its connection in Tracebeam’s center toolbar, then open Network or Console and use your app.

That’s enough for requests and logs. With discovery off, the SDK connects directly to 127.0.0.1:49152 on iOS Simulator or 10.0.2.2:49152 on Android Emulator. You do not need the discovery permissions below. Android still requires its standard INTERNET permission, normally included in Flutter’s debug manifest.

Everything below is optional setup for a specific need.

Physical device (only if needed)

Android over USB (optional)

For a USB-connected Android phone, enable USB debugging and approve your Mac on the phone. With adb from Android SDK Platform-Tools available, run:

adb devices
adb reverse tcp:49152 tcp:49152

Replace the quick start’s TracebeamConnectOptions with these Android development options, keeping the existing kDebugMode guard:

options: const TracebeamConnectOptions(
  host: '127.0.0.1',
  port: 49152,
  discovery: false,
),

Restart the app. Keep Tracebeam in Basic and leave Connect devices over Wi-Fi or Ethernet off: the USB forwarding reaches the Mac’s local listener. No discovery, access key, or certificate setup is needed. Android’s normal INTERNET permission and debug networking policy still apply.

Android Emulator does not need this: its default 10.0.2.2 address already reaches the Mac. For custom ports, multiple devices, or removing forwarding, see Android USB forwarding.

Over Wi-Fi or Ethernet

Enable Settings → Connections → Connect devices over Wi-Fi or Ethernet on the Mac. Put both devices on a trusted local network and replace the connection options with your Mac’s LAN address:

await Tracebeam.connect(
  options: const TracebeamConnectOptions(
    host: '192.168.1.20', // Replace with your Mac's LAN IP.
    port: 49152,
  ),
);

An explicit host bypasses discovery. Basic is unencrypted; use a trusted development network.

iPhone local-network permission

A real iPhone needs local-network permission, even with a direct connection. If your app does not already declare it, add this to the development app’s ios/Runner/Info.plist and rebuild:

<key>NSLocalNetworkUsageDescription</key>
<string>Connect to Tracebeam during development.</string>

Allow the local-network prompt. No NSBonjourServices entry is needed for a direct host connection. This permission step does not apply to the iOS Simulator quick start.

Automatic discovery (optional)

Use discovery only if you want to find Tracebeam without entering the Mac’s address. Remove host and discovery: false from the connection options; discovery is enabled by default. In Basic mode, enable the Mac’s network-access setting for Bonjour advertising.

For iOS discovery, use the local-network description above and add:

<key>NSBonjourServices</key>
<array><string>_tracebeam._tcp</string></array>

On Android, ensure the app’s manifest includes the permissions used for networking and discovery:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

Rebuild after changing platform configuration. If multicast discovery is unavailable, use the direct host connection instead.

Troubleshooting

• No connection: check the Mac is listening in Basic mode and the port matches. Over Wi-Fi, use the Mac’s LAN address. For Android USB forwarding, use 127.0.0.1 and reapply adb reverse if the mapping was lost after reconnecting.
• Changed the plugin or platform permissions: perform a full native rebuild, not hot reload/restart.
• Missing network events: HTTP clients must be created inside the runGuarded zone. Native SDK and WebView traffic is not captured by the Dart interceptor.
• Networking policy blocks the debugger: check your debug manifest/network policy. Keep development-only exceptions out of release configuration.

See connection troubleshooting for permissions, firewall, and mode checks.

Advanced options

Optional Secure mode

Skip this for the Basic quick start. Secure adds authentication and encryption:

1. Choose Secure in Settings → Connections on the Mac.
2. Copy the access key and export the Device CA Certificate.
3. Include the .cer file in your development Flutter assets and declare its path under flutter.assets in the development configuration. Keep this asset and the key out of production builds and source control.
4. Import rootBundle from package:flutter/services.dart and replace the Basic connection call with:

final ca = await rootBundle.load('assets/Tracebeam-Device-CA.cer');
await Tracebeam.connect(
  options: TracebeamConnectOptions(
    host: 'YOUR-MAC.local',
    port: 49152,
    accessKey: const String.fromEnvironment('TRACEBEAM_ACCESS_KEY'),
    deviceCACertificate:
        ca.buffer.asUint8List(ca.offsetInBytes, ca.lengthInBytes),
  ),
);

Provide a nonempty TRACEBEAM_ACCESS_KEY through a local debug run configuration, such as a git-ignored --dart-define-from-file file. Use your actual Mac hostname; 127.0.0.1 and Android Emulator’s 10.0.2.2 are also covered by the Device certificate.

The exported certificate is DER; pass its bytes directly. The SDK handles the certificate conversion and verifies TLS chain and hostname. The Device CA is not the Proxy CA. The built-in debugger socket bypasses HTTP proxies without changing the application’s HTTP clients.

A key or certificate selects Secure even during retries. Secure connection failures never fall back to plaintext. Remove both options and change the Mac to Basic to return to Basic mode.

Capture and state inspection

runGuarded observes supported dart:io HTTP clients created inside its zone, including clients used by Dio. Native SDK and WebView traffic is outside this capture boundary.

Register app-owned Provider, Shared Preferences, Secure Storage, and Go Router integrations for their inspectors. Secure Storage is an explicit opt-in: values are masked by default, and observation starts when a relevant inspector, snapshot, Lab, or recording needs it. Revealed values may enter recordings or exports.

The native plugin remembers the same app installation across reconnects and launches on both simulators and physical devices. Uninstalling, clearing app data, or erasing the simulator resets this identity. It does not restore old capture data or merge simultaneous sessions.

Performance and recording

Capture waits for a valid server welcome. Reconnect queues and socket writes are bounded; queued messages drain in small batches. Ordinary state notifications coalesce, while action-bearing updates retain their notification-time state. This reduces capture overhead but does not move all serialization to a background isolate.

Tracebeam.connection?.diagnostics reports drop reasons, including asynchronous socket-write failures and unconfirmed close-time frames. Network observation counters are separate and runtime-wide. These local counters are not yet forwarded to the desktop Capture Health panel, and unconfirmed frames are not proven losses.

The optional on-device recorder can be exposed through TracebeamDebugRecorderButton(recorder: Tracebeam.recorder). It runs only after the user starts it, needs no Mac connection, and shares a local .tracebeam file through the platform share sheet. Connecting never starts screen capture; visual recording requires a selected screen mode and platform permission. Recording and privacy.