Flutter SDK - Lucent

Lucent’s first-party Flutter SDK is published as lucent_flutter. The MVP supports iOS and Android. Flutter Web is deferred because Flutter Web needs a separate web capture path, while this SDK sends screenshot-mode mobile replay.

Requirements

Flutter >=3.27.0
Dart >=3.6.0
iOS 13.0 or later
Android min SDK 23 or later
A Lucent public key (luc_pk_...)

Install

lucent_flutter is not published on pub.dev yet. Until 0.1.0 is published, install it from the Lucent monorepo or from a local SDK checkout.

dependencies:
  lucent_flutter:
    git:
      url: https://github.com/lucent-ai/mono-lucent.git
      path: sdk-flutter-lucent
      ref: <commit-or-tag>

dependencies:
  lucent_flutter:
    path: ../mono-lucent/sdk-flutter-lucent

After the package is published to pub.dev, use the normal hosted package dependency:

dependencies:
  lucent_flutter: ^0.1.0

Then fetch dependencies:

flutter pub get

For iOS, use the standard Flutter CocoaPods flow:

cd ios
pod install

For Android release builds, make sure your app manifest allows network access. Flutter debug and profile builds may add this automatically, but release apps should include it explicitly in android/app/src/main/AndroidManifest.xml.

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

CocoaPods is the verified iOS packaging path for the MVP. Swift Package Manager support is deferred because Flutter can generate a package identity from the local SDK directory that differs from the pub package name.

Quick start

Set up Lucent before runApp, then wrap your app in LucentWidget.

import 'package:flutter/material.dart';
import 'package:lucent_flutter/lucent_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Lucent().setup(
    const LucentConfig(
      publicKey: 'luc_pk_...',
      metadata: LucentMetadataConfig(
        app: 'Acme Mobile',
        namespace: 'com.acme.mobile',
        version: '1.2.3',
        build: '123',
        release: '1.2.3+123',
      ),
    ),
  );

  Lucent().runZoned(() {
    runApp(const LucentWidget(child: MyApp()));
  });
}

LucentWidget captures screenshot-mode replay, touch events, and app lifecycle events. Keep it near the root of the app so remounts do not reset the replay surface.

Screen tracking

Add LucentObserver() to your MaterialApp navigator observers to emit $screen events and update the replay URL.

MaterialApp(
  navigatorObservers: [LucentObserver()],
  routes: {
    '/': (_) => const HomeScreen(),
    '/checkout': (_) => const CheckoutScreen(),
  },
)

If your router does not use named PageRoutes, call Lucent().screen(...) from your route listener.

await Lucent().screen('checkout', {'step': 'payment'});

You can also customize the observer for apps that need custom route names or route filtering.

LucentObserver(
  nameExtractor: (settings) => settings.name ?? 'unknown',
  routeFilter: (route) => route is PageRoute,
)

Identify users

Sessions start with a generated anonymous ID. Call identify when you know the user, and call resetIdentity on sign out.

await Lucent().identify(
  const LucentUser(
    id: 'user_123',
    email: '[email protected]',
    name: 'Ada Lovelace',
    properties: {'plan': 'pro'},
  ),
);

await Lucent().setUserProperties({'role': 'admin'});
await Lucent().setSessionProperties({'checkoutExperiment': 'variant_a'});
await Lucent().resetIdentity();

Track events

Use track for custom events. Event properties also receive metadata from LucentMetadataConfig.

await Lucent().track('checkout_tapped', {
  'plan': 'pro',
  'source': 'pricing',
});

Control recording

Replay starts automatically by default when the session is sampled in. You can pause, resume, flush, and inspect the current session.

await Lucent().stopSessionRecording();
await Lucent().startSessionRecording(resumeCurrent: true);
await Lucent().flush();
await Lucent().flush(finalFlush: true);

final info = await Lucent().getSessionInfo();
debugPrint(info?.sessionId);

Call Lucent().stop() when you need to tear down the SDK. It stops native recording, clears installed Dart hooks, and performs a final native flush. Use autoStart: false or LucentReplayConfig.eventTriggers when you need to wait for consent or only record after specific events.

await Lucent().setup(
  const LucentConfig(
    publicKey: 'luc_pk_...',
    autoStart: false,
    replay: LucentReplayConfig(
      eventTriggers: ['checkout_tapped'],
    ),
  ),
);

Privacy masking

Flutter replay is privacy-first. Text, text inputs, and images are masked by default. Wrap extra-sensitive regions in LucentMask, and wrap safe public regions in LucentNoMask.

const LucentMask(
  child: PaymentCardForm(),
);

const LucentNoMask(
  child: Text('Public status: ready'),
);

LucentNoMask opts the subtree into replay visibility, so only use it for UI that is safe to show in a session replay.

Logs

When capture.logs is enabled, Lucent captures Flutter debugPrint output. Wrapping runApp in Lucent().runZoned(...) also captures print(...).

Lucent().runZoned(() {
  print('App started');
  runApp(const LucentWidget(child: MyApp()));
});

await Lucent().captureLog(
  'Checkout validation failed',
  level: 'warn',
  properties: {'field': 'zip'},
);

Network breadcrumbs

When capture.network is enabled, Lucent().runZoned(...) installs a zone-scoped dart:io HttpClient wrapper. It captures method, sanitized URL, status, duration, and transfer size for requests made inside the zone.

Lucent().runZoned(() {
  runApp(const LucentWidget(child: MyApp()));
});

For clients that do not use dart:io, call captureNetworkRequest from your HTTP wrapper or interceptor.

final response = await Lucent().captureNetworkRequest<Response>(
  method: 'GET',
  url: 'https://api.example.com/products?token=secret',
  request: () => client.get('/products'),
  status: (response) => response.statusCode,
  transferSize: (response) => response.bodyBytes.length,
);

You can also send a manual network breadcrumb.

await Lucent().captureNetwork(
  method: 'POST',
  url: 'https://api.example.com/checkout',
  status: 200,
  durationMs: 184,
);

Lucent strips URL user info, query strings, and fragments before upload. Request bodies, response bodies, and headers are not captured.

Errors and crashes

Lucent captures Flutter framework errors and PlatformDispatcher async errors when the corresponding capture options are enabled. Use captureException for handled exceptions and addExceptionStep for lightweight breadcrumbs.

try {
  await checkout();
} catch (error, stackTrace) {
  await Lucent().addExceptionStep('Checkout failed after payment tap');
  await Lucent().captureException(error, stackTrace: stackTrace);
  rethrow;
}

Native uncaught exceptions are stored synchronously and emitted as $native_crash on the next launch. If your app already has a top-level async error handler, pass it to runZoned.

Lucent().runZoned(
  () => runApp(const LucentWidget(child: MyApp())),
  onError: (error, stackTrace) {
    // Forward to your existing crash reporter.
  },
);

Example app

The SDK package includes an example app that exercises setup, LucentWidget, LucentObserver, masking, custom events, manual network breadcrumbs, handled exceptions, and flush.

cd sdk-flutter-lucent/example
flutter pub get
flutter run

Next steps

Flutter support reference - options, replay envelope, persistence, limitations, and troubleshooting.
Replay endpoint - ingest payload schema.

​Requirements

​Install

​Quick start

​Screen tracking

​Identify users

​Track events

​Control recording

​Privacy masking

​Logs

​Network breadcrumbs

​Errors and crashes

​Example app

​Next steps

Requirements

Install

Quick start

Screen tracking

Identify users

Track events

Control recording

Privacy masking

Logs

Network breadcrumbs

Errors and crashes

Example app

Next steps