Record what a user does in your Flutter app and replay it in any browser.
Screens, taps, network requests, errors and logs on a single timeline, exported as
one self-contained .html file. Attach it to a ticket, send it over Slack,
open it with a double click. No server, no account, no internet.
β¨ Highlights
| Debug the session | Share the evidence |
|---|---|
| π¬ Step-by-step replay: every screen, tap and scroll, in order | π¦ One HTML file: opens offline in any browser |
| π Network traffic: headers, bodies, JSON viewer and Copiar cURL | π€ Export button: embedded HTML or encrypted .flowx in one tap |
| π Errors with context: stack trace plus the screen where it happened | π€ Export for AI: a small .zip with automatic findings for Claude, ChatGPT or Gemini |
π Search everything: βK across URLs, bodies, headers, logs and notes |
ποΈ Export to video: MP4 in 16:9 or 9:16, rendered in the browser |
| πΊοΈ Flow map: every screen and the action behind each transition | π Steps to reproduce: a bug report for Jira, GitHub or Slack |
| π‘ System signals: background, connection, keyboard, field edits, slow frames | ποΈ Notes on any action: saved inside the same .html |
π Private by default: passwords masked in screenshots, RedactedZone |
πͺΆ Light on the app: capture outside animations, exports in an isolate |
π How it works
Recording runs inside your app while testers use it. When something looks wrong, they export the session and send one file; whoever opens it sees exactly what happened, in order, with the requests and errors next to each tap.
π€ Install with an AI assistant
Paste this prompt into your coding assistant (Claude Code, Cursor, Copilot, Geminiβ¦) from the root of your Flutter project:
Install flog_flow with its built-in export button enabled. The button must directly export and share a self-contained HTML report with all captured session details, excluding secrets. Adapt to the existing architecture.
1. Add flog_flow and the companion packages used by the app: flog_flow_dio for Dio and flog_flow_http for package:http.
2. After WidgetsFlutterBinding.ensureInitialized() and before runApp(), await FlogFlow.instance.start(appName: '<app name>', config: const CaptureConfig(offlineMode: true, captureNetwork: true, captureNetworkBodies: true, captureLogs: true)). Use the app's test/development flag, or !kReleaseMode, to enable recording and the button together.
3. Preserve the root app builder and wrap its output with FlogFlogScope(showExportButton: enabled, exportButton: const FlogExportButton(format: FlogExportFormat.html), child: child!). Register a fresh FlogFlow.instance.newNavigatorObserver() for each Navigator through the router's observer API. Use the built-in button; do not create another export UI or format picker.
4. Instrument every Dio/http client with FlogDioInterceptor()/FlogHttpClient(). Connect FlogLogCapture and chain FlutterError.onError and PlatformDispatcher.instance.onError to recordError(), preserving existing handlers.
5. Keep screenshots, interactions, full network headers/bodies within configured limits, errors and logs. Redact only secret values (tokens, cookies, passwords, API keys) from captured URLs, headers, bodies, logs and errors, and mask secrets in screenshots. Do not modify live requests or responses. The SDK does not automatically redact network/log secrets; implement this in the integration.
6. Run flutter pub get and flutter analyze. Verify that the built-in button exports embedded HTML with complete captured details and no secret values.
π Quick start
flutter pub add flog_flow
flutter pub add flog_flow_dio # if you use Dio
flutter pub add flog_flow_http # if you use package:http
import 'package:flog_flow/flog_flow.dart';
import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
const enabled = !kReleaseMode; // or your app's test/development flag
if (enabled) await FlogFlow.instance.start(appName: 'MyApp');
runApp(MaterialApp(
navigatorObservers: [FlogFlow.instance.newNavigatorObserver()],
builder: (context, child) => FlogFlogScope(
showExportButton: enabled, // optional; false by default
child: child!,
),
home: const Scaffold(body: Center(child: Text('My app'))),
));
}
π€ Export and share
Built-in button (optional)
Enable the floating button with showExportButton: true on FlogFlogScope
(see Quick start). The control offers embedded HTML and
encrypted .flowx, asks for a passphrase if none is configured, and opens
the system share sheet. It stays outside the screenshots and tap recording,
respects safe areas, and works in MaterialApp.builder and
MaterialApp.router.builder without an ancestor Navigator.
The button is off by default. It does not start recording or register
navigation/network observers: keep those integrations from Quick start.
Your app decides which environments enable recording and the control.
share_plus is included; no extra import or application dependency is needed.
Customize the position or use a fixed format without the format picker:
FlogFlogScope(
showExportButton: true,
exportButtonAlignment: Alignment.bottomLeft,
exportButtonPadding: const EdgeInsets.all(16),
exportButton: const FlogExportButton(format: FlogExportFormat.flowx),
child: child!,
);
For .flowx, the button uses its passphrase argument, then
CaptureConfig.encryptionPassphrase, or asks the tester. The entered key is
not stored in the recorder. Open the file through Abrir in the HTML viewer
and enter the same key. HTML includes the viewer, manifest and screenshots in
one unencrypted file; it needs no server or passphrase.
You can also put FlogExportButton() in a Scaffold's floatingActionButton,
or handle the file without opening the share sheet:
FlogExportButton(
format: FlogExportFormat.html,
share: false,
onExported: (file) => saveEvidence(file), // your own save/upload action
onError: (error, stack) => reportExportError(error, stack),
);
Actions for your own UI
Leave showExportButton off and use the same actions from an existing
settings menu, AppBar, keyboard shortcut or custom button:
final actions = FlogExport(); // or FlogExport(recorder: myRecorder)
final html = await actions.exportFile(); // embedded HTML, screenshots included
final encrypted = await actions.exportFile(
format: FlogExportFormat.flowx,
passphrase: keyFromYourUI,
);
// Share an existing file without exporting again:
final status = await actions.shareFile(html, sharePositionOrigin: buttonRect);
// Or export and share in one call:
final result = await actions.exportAndShare(
format: FlogExportFormat.flowx,
passphrase: keyFromYourUI,
sharePositionOrigin: buttonRect,
);
// result.file always identifies the generated file on successful return.
// result.shareStatus: shared, dismissed, or unavailable (send unconfirmed).
On iPad, custom actions must pass the invoking control's global rectangle as
sharePositionOrigin (box.localToGlobal(Offset.zero) & box.size). The built-in
button supplies it automatically. File sharing is not supported on Linux;
shareFile returns unavailable and the file remains available to your own
save UI. Native file sharing uses share_plus.
The button calls onExported before sharing and onCompleted with the final
FlogExportResult; cancellation never displays a successful-share checkmark.
Errors use onError if provided, otherwise the console, and allow retrying.
Session retention: FlogExport and the button default to
deleteAfterExport: false, so you can export both formats, continue recording
and retry sharing. Set it to true explicitly to delete the session after the
file is generated. Existing FlogFlow.export() / exportFlowx() keep their
current CaptureConfig.deleteAfterExport behavior. Starting a new session
still deletes previous session data; preserve the exported files yourself.
π§° Features
The screenshots and recordings below come from a real IMDUMB session on iOS: 16 screens, 39 interactions, 31 requests and two recorded errors. Documentation copies have authorization headers removed.
One HTML file, nothing else
The whole session (timeline, screenshots and viewer) lives in a single .html
that opens offline in Chrome, Safari, Edge or Firefox. Anyone can open it: no
SDK, no dashboard, no login. Data never leaves the device unless someone
shares the file.

Step-by-step replay
Every screen and every interaction, in order: the exact point of each tap, the direction of each scroll, the navigation it triggered and what the screen looked like at that moment. Play it like a video or move with the arrow keys, and copy any screenshot (with the tap marker) in one click.

Network traffic
Each request appears on the timeline next to the tap that caused it: method,
URL, status and duration, plus headers and bodies with a JSON viewer.
Copiar cURL (copy as cURL) repeats the exact request from a terminal. Works with Dio
(flog_flow_dio), package:http (flog_flow_http) or any client through
FlogFlow.instance.recordHttpCall.
dio.interceptors.add(FlogDioInterceptor()); // Dio
http.runWithClient(() => runApp(const MyApp()), () => FlogHttpClient()); // package:http
Large responses remain fully available in the report. Above 4,000 formatted
lines, the viewer uses plain text to keep rendering responsive; Copiar todo
copies all captured content. Capture limits (offlineBodyLimit on the network
adapters) are independent of this display threshold.

This request is from the recorded session. Its authorization header was redacted before generating documentation media.
Errors with context
Every error is stored with its stack trace and a screenshot of the screen it happened on, in the same timeline as the taps and requests that led to it. Connect the global handlers once and nothing escapes.
final onFlutterError = FlutterError.onError;
FlutterError.onError = (details) {
FlogFlow.instance.recordError(details.exception, stackTrace: details.stack);
onFlutterError?.call(details);
};
final onPlatformError = PlatformDispatcher.instance.onError;
PlatformDispatcher.instance.onError = (error, stack) {
FlogFlow.instance.recordError(error, stackTrace: stack);
return onPlatformError?.call(error, stack) ?? false;
};

Export for AI
One click builds a configurable .zip for analysis in Claude, ChatGPT or
Gemini: a readable session.md, a
session.json and the key screenshots. It starts with automatic findings:
failed, slow or repeated requests, identical responses, unlabeled taps, frozen
UI and connection drops. Secrets (tokens, cards, passwords) are hidden by
default.

π Read the generated session summary.
Export to video
Turns the session (or a selected range) into an MP4, rendered in the browser: animated taps and scrolls, screen transitions, and a side panel with the requests and notes as they happen. Horizontal 16:9 or vertical 9:16. Evidence for the ticket without having recorded the screen.
βΆοΈ Watch or download the generated MP4: 97 seconds, 1280 Γ 720, generated by the viewer from this session.

The reviewer note shown in the video was added for this demonstration.
Steps to reproduce
Select a range of the timeline and get the bug report written: environment, precondition, numbered steps (in Spanish, like the viewer: "Toca Β«PagarΒ» β se abre Β«CheckoutΒ»"), observed result (errors, failed requests) and expected result. Markdown for Jira, GitHub or Slack, editable before copying.

π Read the generated reproduction steps.
Notes on any action
Testers write a note on the exact action where something went wrong. Notes
show up in the video, the steps to reproduce and the AI export, and
Descargar copia con notas (download copy with notes) saves them inside the
same .html for the next person.

The note is a demonstration annotation added to the recorded error.
Search everything
βK / Ctrl+K searches URLs, request and response bodies, headers, logs,
errors and notes. Opening a result jumps to that action and highlights every
match.

Flow map
All the screens visited as a map, with the transitions between them and the action that triggered each one. The fastest way to see the path a user took.

System signals
The timeline also shows what the app went through, not only what the user tapped:
- app sent to background and back (and for how long);
- connection changes: wifi, mobile data, none;
- keyboard opened and closed;
- which text fields were edited (never what was typed);
- slow frames and UI freezes (profile/release builds).

This session includes a 26-second background interval and field-edit events. It contains no connectivity changes, keyboard events or slow-frame events.
Private by default
- Password fields are masked in screenshots automatically; mask every text
field with
CaptureConfig(maskTextFields: true). - Wrap anything else sensitive in
RedactedZone. - Nothing stays on disk between sessions.
- Full headers and bodies are enabled by default with
offlineMode: true. Set it tofalseto omit headers and use body previews. Raw HTML exports can contain authorization tokens, cookies and personal data. - Need a protected file?
exportFlowx(passphrase: β¦)writes an AES-256 encrypted.flowxthat opens from the Abrir button of any report.

The name field is masked in the original capture. This session does not contain a password field or an encrypted-file export.
Logs and breadcrumbs
Capture debugPrint output (and print, through FlogLogCapture.zoneSpec();
opt-in), add your own breadcrumbs, and label the action that triggers a
navigation so the flow reads like a story.
FlogLogCapture.installDebugPrintCapture(); // with CaptureConfig(captureLogs: true)
FlogFlow.instance.breadcrumb('Cart updated', data: {'items': 3});
FlogFlow.instance.tag('User clicks "Pay"'); // right before Navigator.push

These two recorded breadcrumbs identify edited fields without their values. This session contains no captured print or debugPrint logs.
Keep only the sessions that fail
Record always but keep the flow only when something breaks, and export it the moment the error happens.
await FlogFlow.instance.start(
appName: 'MyApp',
config: const CaptureConfig(recordOnErrorOnly: true),
);
FlogFlow.instance.onErrorRecorded = () async {
final file = await FlogFlow.instance.exportIfError();
// upload or share `file`
};

The session illustrates recorded errors; the retention policy is configured in the SDK with the code above.
Light on the app
Screenshots are taken outside animations and encoded during idle time, kept on
disk instead of in memory; exports run in an isolate, and the expensive
options are opt-in. Everything is tunable in CaptureConfig.
For a lighter recording, reduce screenshot size and disable body capture:
const CaptureConfig(
offlineMode: false,
captureNetworkBodies: false,
framePerInteraction: false,
pixelRatio: 0.75,
jpegQuality: 55,
);
The media above demonstrate the exported session; they do not measure recording overhead.
βοΈ Configuration
FlogFlow.instance.start(appName: β¦, config: CaptureConfig(β¦)). The most used
options:
| Option | Default | What it does |
|---|---|---|
captureNetwork |
true |
Records requests from a network adapter |
captureNetworkBodies |
true |
Adds the full URL and body previews |
offlineMode |
true |
Full bodies and headers (enables Copiar cURL); sensitive |
captureLogs |
false |
Records debugPrint/print output |
framePerInteraction |
true |
One screenshot per tap, frozen at the moment of the tap |
maskPasswordFields |
true |
Masks password fields in screenshots |
maskTextFields |
false |
Masks every text field |
recordOnErrorOnly |
false |
Keeps the session only if an error happens |
recordAppLifecycle, recordConnectivity, recordKeyboard, recordFieldEdits, recordSlowFrames |
true |
System signals on the timeline |
pixelRatio / jpegQuality |
1.0 / 65 |
Screenshot sharpness and size |
π§© Companion packages
| Package | Use it when |
|---|---|
flog_flow_dio |
Your app uses Dio |
flog_flow_http |
Your app uses package:http (or a package built on it) |
π± Platforms
| Android | iOS | macOS | Windows | Linux | Web |
|---|---|---|---|---|---|
| β | β | β | β | β | β |
Flutter web is not supported: the recorder uses dart:io. The viewer inside
the HTML is in Spanish.
π License
MIT. See LICENSE.
If flog_flow saved you a debugging session, give it a π on pub.dev.
Libraries
- flog_flow
- flog_flow

