Flutter SDK

Replayfy records every screen, tap, network request, and error in your Flutter app so you can replay real sessions, understand drop-off, and fix bugs from an exact reproduction.

Install

flutter pub add replayfy_flutter

dependencies:
  replayfy_flutter: ^0.0.7

Android — the native recording engine resolves automatically from Maven Central (mavenCentral() is already in the default Flutter Android template), so no repository configuration is needed. If you pin a pre–Maven Central version, add maven { url 'https://jitpack.io' } to your app’s android/settings.gradle as a fallback.iOS — requires a deployment target of iOS 15 or higher.

Initialize

Start Replayfy as early as possible

Boot the SDK inside Replay.runZoned so console output and uncaught async errors are captured too.

main.dart

import 'package:flutter/widgets.dart';
import 'package:replayfy_flutter/replayfy_flutter.dart';

void main() => Replay.runZoned(() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Replay.start(const ReplayConfig(
    apiKey: 'rpl_pk_YOUR_KEY',
    apiHost: 'https://us.replayfy.app',  // or your self-hosted API URL
  ));

  runApp(const MyApp());
});

Wire up frame capture and screen tagging

Use the provided app builder so Replayfy can capture each frame, and add the navigator observer to auto-tag screens.

MaterialApp(
  builder: Replay.appBuilder,
  navigatorObservers: [ReplayNavigatorObserver()], // auto-tags screens
  home: const HomePage(),
);

Verify

Run the app, interact with it for a few seconds, then reload. Your first session appears in the dashboard within a minute.

Configuration

Every option on ReplayConfig:

Option	Type	Default	Description
`apiKey`	`String`	— (required)	Your project API key from the dashboard.
`apiHost`	`String`	— (required)	Your Replayfy ingest host, e.g. `https://us.replayfy.app` (or your self-hosted API URL).
`distinctId`	`String?`	`null`	Known user id at start; otherwise an install-stable anonymous id is used.
`recordScreen`	`bool`	`true`	Capture screen frames for replay.
`recordNetwork`	`bool`	`true`	Capture network requests and responses.
`recordConsole`	`bool`	`true`	Capture console output (`print` / `debugPrint`). Requires `Replay.runZoned`.
`recordErrors`	`bool`	`true`	Capture unhandled errors and crashes.
`recordPerformance`	`bool`	`true`	Capture performance vitals (cold start, frame drops, memory, thermal, battery).
`maskAllInputs`	`bool`	`false`	Automatically mask every text input.
`autoScreenName`	`bool`	`true`	Automatically tag screens from the navigator.
`useRemoteConfig`	`bool`	`true`	Let the dashboard override capture settings remotely.
`debug`	`bool`	`false`	Verbose SDK logging.

API reference

All methods are static on Replay. Most return Future<void>.

Lifecycle

Method	Description
`Replay.start(ReplayConfig config)`	Boot the SDK and start recording.
`Replay.stop()`	Stop and finalize the session.
`Replay.pauseRecording()`	Pause capture without ending the session.
`Replay.resumeRecording()`	Resume after a pause.
`Replay.startNewSession()`	End the current session and begin a fresh one.
`Replay.cancelSession()`	Discard the in-flight session without uploading.
`Replay.isRecording()`	Returns `Future<bool>` — whether capture is active.
`Replay.currentSessionId()`	Returns `Future<String?>` — the current session id.
`Replay.stopApplicationAndUploadData()`	Force-upload everything immediately (e.g. right before a forced logout).

Identity & events

Method	Description
`Replay.identify(String distinctId, {Map<String, Object?> properties})`	Associate the session with a known user and set user properties — including a `picture` (alias `avatar`) https image URL used as the user’s avatar in the dashboard.
`Replay.track(String event, {Map<String, Object?> properties})`	Record a custom analytics event.
`Replay.captureException(Object error, {StackTrace? stackTrace, bool handled})`	Capture a handled exception (`handled: true` by default).
`Replay.trackInput(String label, String value, {bool masked})`	Record a text field’s value; pass `masked: true` to drop it to `"***"`.

Screens, tags & properties

Method	Description
`Replay.tagScreenName(String name)`	Manually tag the current screen.
`Replay.excludeScreen(String name)`	Exclude a screen from frame capture by name (case-insensitive; matched against the tagged / auto-tagged screen name). While it’s foreground the screenshot loop pauses — taps, network, and console keep flowing — and resumes on the next non-excluded screen. Distinct from `occludeSensitiveScreen`, which records but blanks the frame.
`Replay.unexcludeScreen(String name)`	Stop excluding a screen — frame capture resumes next time it’s shown.
`Replay.setExcludedScreens(List<String> names)`	Replace the entire excluded-screens list in one call.
`Replay.addTagWithProperties(String tag, {Map<String, Object?> properties})`	Add a tag with arbitrary properties.
`Replay.setUserProperty(String key, Object? value)`	Set a property that sticks to the user.
`Replay.setSessionProperty(String key, Object? value)`	Set a property scoped to this session only.
`Replay.setMetadata(String key, Object? value)`	Attach metadata to the session.
`Replay.markSessionAsFavorite()`	Flag the current session as a favorite.
`Replay.reportBugEvent(String title, {String description})`	Log a bug report event on the timeline.
`Replay.log(String message, {String level})`	Write a message into the console timeline.

Runtime configuration

Method	Description
`Replay.setAutomaticScreenNameTagging(bool enabled)`	Toggle automatic screen tagging at runtime.
`Replay.enableAdvancedGestureRecognizer(bool enabled)`	Additionally capture pinch and rotate gestures, on top of the always-on tap / swipe / long-press. Off by default.
`Replay.setMultiSessionRecord(bool enabled)`	Record multiple sessions per app launch (default), or only one — when disabled, the current/next session records and then no further sessions open this process.
`Replay.allowShortBreakForAnotherApp(bool allow, {int breakWindowMs = 30000})`	Keep the same session across a brief switch to another app — a background gap up to `breakWindowMs` resumes the session; a longer gap starts a fresh session on return.
`Replay.setAppVersion(String version, {String build})`	Set the app version and build number.
`Replay.setPushNotificationToken(String token, {String platform})`	Register a push token (e.g. `platform: 'fcm'`).

Deep links

Method	Description
`Replay.urlForCurrentSession()`	Returns `Future<String?>` — a dashboard link to the current session.
`Replay.urlForCurrentUser()`	Returns `Future<String?>` — a dashboard link to the current user.

Privacy

Method	Description
`Replay.setMaskStyle(ReplayMaskStyle style)`	Set the global mask style for bulk and whole-screen regions.
`Replay.occludeAllTextFields(bool enabled)`	Mask all single-line text fields.
`Replay.occludeAllTextView(bool enabled)`	Mask all multi-line text views.
`Replay.occludeSensitiveScreen(bool enabled)`	Mask the entire current screen.
`Replay.optOut(bool optedOut)`	Persistent kill switch — stop all recording.
`Replay.optIn()`	Resume recording (same as `optOut(false)`).
`Replay.isOptedOut()`	Returns `Future<bool>` — the current opt-out state.

Privacy & masking

Replayfy is built to keep sensitive data off the wire. Mask a widget — wrap anything sensitive; it is blurred (default), covered, or pixelated in the recording:

ReplayMask(
  maskStyle: ReplayMaskStyle.blur, // .blur | .overlay | .pixelate
  child: Text('•••• •••• •••• 4242'),
);

Mask a text input’s value from its callback — the value is dropped to "***" and never leaves the device:

TextField(
  obscureText: true,
  onSubmitted: (v) => Replay.trackInput('Password', v, masked: true),
);

Bulk & whole-screen masking:

await Replay.setMaskStyle(ReplayMaskStyle.pixelate);
await Replay.occludeAllTextFields(true);   // all single-line text fields
await Replay.occludeAllTextView(true);     // all multi-line text views
await Replay.occludeSensitiveScreen(true); // the entire screen

Or mask every input from the start with maskAllInputs: true in ReplayConfig. GDPR opt-out — a persistent kill switch that survives relaunches:

await Replay.optOut(true);            // stop all recording
await Replay.optIn();                 // resume
final out = await Replay.isOptedOut(); // bool

Identify users

Tie sessions to real users with identify.

Track events

Send custom events and build funnels.

Privacy & masking

Redact sensitive data before it leaves the device.

Get started

Self-hosting

Install the SDK

Products

Platform

Guides

Help

Install

Initialize

Verify

Configuration

API reference

Lifecycle

Identity & events

Screens, tags & properties

Runtime configuration

Deep links

Privacy

Privacy & masking

Identify users

Track events

Privacy & masking

​Install

​Initialize

​Verify

​Configuration

​API reference

​Lifecycle

​Identity & events

​Screens, tags & properties

​Runtime configuration

​Deep links

​Privacy

​Privacy & masking

Identify users

Track events

Privacy & masking

Install

Initialize

Verify

Configuration

API reference

Lifecycle

Identity & events

Screens, tags & properties

Runtime configuration

Deep links

Privacy

Privacy & masking