Skip to main content

flog_flow 0.7.3 copy "flog_flow: ^0.7.3" to clipboard
flog_flow: ^0.7.3 copied to clipboard

Records the user journey in a Flutter app (screens, taps, network, logs, errors) and exports it as one self-contained HTML file to replay in any browser.

FlogFlow: every tap, request and error, replayed from one HTML file

pub.dev version pub.dev likes pub.dev points MIT license Android, iOS, macOS, Windows and Linux

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.

Watch the demo: a real recorded session exported to MP4

✨ 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 #

1. Use your app. 2. Export one file with the built-in button. 3. Replay it in any browser

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.

Self-contained HTML report opened in the browser

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.

Stepping through scrolling, taps, navigation and an error

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.

Request headers, response JSON and copy as cURL

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;
};

Recorded error with stack trace and the screen where it occurred

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.

AI export options, completed ZIP and generated session summary

πŸ“„ 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.

Preview of the generated session video

▢️ Watch or download the generated MP4: 97 seconds, 1280 Γ— 720, generated by the viewer from this session.

Replay of a recorded iOS 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.

Generated steps to reproduce for the selected error sequence

πŸ“„ 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.

Adding a reviewer note and downloading an HTML copy with the note

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.

Searching Spider-Man in response bodies and jumping to a highlighted 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.

Recorded screens connected by navigation and interaction arrows

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).

App background and foreground events in the recorded timeline

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 to false to 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 .flowx that opens from the Abrir button of any report.

Masked name field in a recorded screen

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

Field-edit breadcrumbs without the text entered

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 two recorded errors filtered in the events view

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.

12
likes
150
points
1.59k
downloads

Documentation

API reference

Publisher

verified publisheralecodeando.dev

Weekly Downloads

Records the user journey in a Flutter app (screens, taps, network, logs, errors) and exports it as one self-contained HTML file to replay in any browser.

Homepage

Topics

#debugging #session-replay #testing #network

License

MIT (license)

Dependencies

archive, cryptography, flutter, image, path, path_provider, share_plus

More

Packages that depend on flog_flow