https://github.com/tracewayapp/traceway-flutter
Full session replays for your flutter app. Efficient recording across Android, iOS and web. Compatible with Traceway.
https://github.com/tracewayapp/traceway-flutter
flutter observability session-replay
Last synced: 2 months ago
JSON representation
Full session replays for your flutter app. Efficient recording across Android, iOS and web. Compatible with Traceway.
- Host: GitHub
- URL: https://github.com/tracewayapp/traceway-flutter
- Owner: tracewayapp
- License: mit
- Created: 2026-04-09T15:57:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-16T05:23:18.000Z (3 months ago)
- Last Synced: 2026-04-28T03:42:02.516Z (2 months ago)
- Topics: flutter, observability, session-replay
- Language: Dart
- Homepage:
- Size: 3.79 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Traceway Flutter SDK
Error tracking and screen recording for Flutter apps. Capture exceptions with full stack traces and the last 10 seconds of screen recording — automatically.
[Traceway](https://tracewayapp.com) is a completely open-source error tracking platform. You can [self-host](https://docs.tracewayapp.com/server) it or use [Traceway Cloud](https://tracewayapp.com).
## Features
- Automatic capture of all Flutter errors (framework, platform, and async)
- Full Dart stack traces
- Screen recording — last ~10 seconds encoded as MP4 video
- Touch/click positions rendered on recordings
- Privacy masking — blur or blank sensitive UI regions in recordings
- Disk persistence — pending exceptions survive app restarts
- Gzip-compressed transport
- Simple one-line setup
## Installation
```bash
flutter pub add traceway
```
## Quick Start
Wrap your app with `Traceway.run()`:
```dart
import 'package:flutter/material.dart';
import 'package:traceway/traceway.dart';
void main() {
Traceway.run(
connectionString: 'your-token@https://your-traceway-instance.com/api/report',
options: TracewayOptions(
screenCapture: true,
version: '1.0.0',
),
child: MyApp(),
);
}
```
That's it. All uncaught exceptions are captured automatically.
## Manual Capture
```dart
// Capture a caught exception
try {
await riskyOperation();
} catch (e, st) {
TracewayClient.instance?.captureException(e, st);
}
// Capture a message
TracewayClient.instance?.captureMessage('User completed checkout');
// Force send pending events
await TracewayClient.instance?.flush();
```
## Options
| Option | Default | Description |
|--------|---------|-------------|
| `sampleRate` | `1.0` | Error sampling rate (0.0 - 1.0) |
| `screenCapture` | `false` | Record last ~10 seconds of screen |
| `debug` | `false` | Print debug info to console |
| `version` | `''` | App version string |
| `debounceMs` | `1500` | Milliseconds before sending batched events |
| `retryDelayMs` | `10000` | Retry delay on failed uploads |
| `capturePixelRatio` | `0.75` | Screenshot resolution scale factor |
| `maxBufferFrames` | `150` | Max frames in recording buffer (~10s at 15fps) |
| `fps` | `15` | Frames per second for screen capture (1–59) |
| `maxPendingExceptions` | `5` | Max exceptions held in memory before oldest is dropped |
| `persistToDisk` | `true` | Persist pending exceptions to disk so they survive app restarts |
| `maxLocalFiles` | `5` | Max exception files stored on disk |
| `localFileMaxAgeHours` | `12` | Hours after which unsynced local files are deleted |
## Platform Setup
Traceway needs network access to send error reports. Depending on the platform, you may need to add permissions manually.
### Android
Add the `INTERNET` permission to `android/app/src/main/AndroidManifest.xml`:
```xml
com.apple.security.app-sandbox
com.apple.security.network.client
```
### iOS
No additional configuration is required. iOS apps can make HTTPS requests by default.
## Screen Recording
When `screenCapture: true`, the SDK:
1. Wraps your app in a `RepaintBoundary`
2. Captures frames at ~15fps into a circular buffer
3. On exception, encodes the last ~10 seconds to MP4
4. Sends the video alongside the stack trace
Touch and click positions are drawn directly onto the recorded frames (invisible to the user) so you can see exactly what the user was doing before the crash.
## Privacy Masking
Use `TracewayPrivacyMask` to hide sensitive content in screen recordings. Masked regions are applied to the recorded frames only — the user sees no visual change in the live app.
**Blur (pixelation):**
```dart
TracewayPrivacyMask(
child: Text('4242 4242 4242 4242'),
)
```
The default mode is `TracewayMaskMode.blur()` which pixelates the region. You can control the intensity with the `ratio` parameter (0.0 = light, 1.0 = heavy):
```dart
TracewayPrivacyMask(
mode: TracewayMaskMode.blur(ratio: 0.5),
child: CreditCardWidget(),
)
```
**Blank (solid fill):**
```dart
TracewayPrivacyMask(
mode: TracewayMaskMode.blank(color: Color(0xFF000000)),
child: SensitiveDataWidget(),
)
```
This replaces the region with a solid color (black by default) in the recording.
## Platform Support
| Platform | Error Tracking | Screen Recording |
|----------|---------------|-----------------|
| iOS | Yes | Yes |
| Android | Yes | Yes |
| macOS | Yes | Yes |
| Web | No | No |
For Flutter web, use the JS SDK instead — see [Flutter Web](#flutter-web) below.
## What Gets Captured Automatically
- **Flutter framework errors** — rendering, layout, gestures via `FlutterError.onError`
- **Platform errors** — native plugin crashes via `PlatformDispatcher.onError`
- **Uncaught async errors** — unhandled futures via `runZonedGuarded`
## Flutter Web
This SDK does not support Flutter web. For web apps, use the [`@tracewayapp/frontend`](https://docs.tracewayapp.com/client/js-sdk?sdk=js-generic) JS SDK which provides rrweb session replay and automatic fetch instrumentation.
**Add the CDN script to `web/index.html`:**
```html
Traceway.init("your-token@https://traceway.example.com/api/report");
```
Alternatively, if you use npm in your Flutter web project:
```bash
npm install @tracewayapp/frontend
```
```html
import { init } from '@tracewayapp/frontend';
init('your-token@https://traceway.example.com/api/report');
```
See the full [JS SDK documentation](https://docs.tracewayapp.com/client/js-sdk?sdk=js-generic) for all options.
## Links
- [Traceway Website](https://tracewayapp.com)
- [Traceway GitHub](https://github.com/tracewayapp/traceway)
- [Documentation](https://docs.tracewayapp.com/client/flutter?sdk=flutter)
- [Flutter SDK Source](https://github.com/tracewayapp/traceway-flutter)
## License
MIT