Auto Capture

​

SDK Configuration

1. Userpilot.initialize(..., UserpilotOptions(...)) — starts the native Userpilot SDK and, when autocapture options are provided, starts the Dart autocapture pipeline.
2. UserpilotAutocaptureWidget(child: ...) — wraps your app so the SDK can attach a global pointer route and listen for scroll settle notifications (PageView, TabBarView, wheel pickers).
3. UserpilotAutocaptureNavigatorObserver() — added to each Navigator you want tracked for $screen and dialog/bottom-sheet view_presented events.

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

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Screen and interaction capture are opt-in (default false).
  final options = UserpilotOptions(
    logging: true,
    enableScreenAutoCapture: true,
    enableInteractionAutoCapture: true,
    enableInteractionAccessibilityLabelCapture: true,
    enableInteractionTextCapture: true,
    enableInteractionValueCapture: false,
  );
  Userpilot.initialize('<APP_TOKEN>', options);

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return UserpilotAutocaptureWidget(
      child: MaterialApp(
        navigatorObservers: [UserpilotAutocaptureNavigatorObserver()],
        home: const HomePage(),
      ),
    );
  }
}

​

Screen Capture

​

GoRouter

final _router = GoRouter(
  observers: [UserpilotAutocaptureNavigatorObserver()],
  routes: [
    GoRoute(path: '/', builder: (_, __) => const HomePage()),
    ShellRoute(
      observers: [UserpilotAutocaptureNavigatorObserver()],
      builder: (context, state, child) => MyShellScaffold(child: child),
      routes: [/* ... */],
    ),
  ],
);

• StatefulShellRoute.indexedStack keeps every branch alive in an IndexedStack. Switching tabs does not push or pop, so $screen only fires on the first visit to each branch. Use a non-stateful ShellRoute if you need a screen event on every tab swap.
• CustomTransitionPage must be constructed with key: state.pageKey and name: state.matchedLocation. Without name, the generated page route is unnamed and no $screen event is emitted.

​

AutoRoute

return MaterialApp.router(
  routerConfig: _appRouter.config(
    navigatorObservers: () => [UserpilotAutocaptureNavigatorObserver()],
  ),
);

​

Interaction Capture

​

Component Value Gating

​

Privacy Controls

​

Wire Metadata Keys

​

hierarchy Format

• attr__desc — only the semantics accessibility label for that ancestor. Omitted when enableInteractionAccessibilityLabelCapture: false, under UserpilotRedactText, or when no label exists.
• attr__id — Semantics.identifier or ValueKey value when present. Semantics.identifier is omitted when enableInteractionAccessibilityLabelCapture: false or under UserpilotRedactText; ValueKey remains structural metadata.
• attr__index — the widget’s index among its siblings. For a child of a lazy list (ListView.builder, SliverList), this is the item’s index in the list, so the same row reports the same value at any scroll position.

​

Tuning maxHierarchyDepth

UserpilotOptions options = UserpilotOptions();
options.enableInteractionAutoCapture = true;
options.maxHierarchyDepth = 25;

​

UserpilotRedactText

UserpilotRedactText(
  child: ElevatedButton(
    onPressed: _confirm,
    child: const Text('Account 4242 4242 4242 4242'),
  ),
);

​

UserpilotIgnoreInteractions

UserpilotIgnoreInteractions(
  child: ElevatedButton(
    onPressed: _internalAction,
    child: const Text('Internal-only action'),
  ),
);

​

Runtime Controls

Userpilot.stopAutocapture();   // stops capture; preserves options
Userpilot.resumeAutocapture(); // resumes capture

​

Limitations

• Routes pushed without RouteSettings.name are ignored for screen autocapture. Always pass a name (or use named routes via onGenerateRoute) when a route should be tracked as a screen.
• Multiple Navigator instances — every nested Navigator has its own observers list. Add UserpilotAutocaptureNavigatorObserver() to each navigator you want tracked.
• Non-PageRoute transitions — the observer only treats PageRoute subclasses as screens. Custom transitions that extend TransitionRoute directly are not captured. Both go_router and auto_route produce PageRoute subclasses for their default page builders, so this only affects bespoke routing implementations.
• Text-field attachment — editable fields are discovered when autocapture is registered and when focus moves (and during internal rescans). A field that appears without a focus change may not be watched until the next scan trigger.
• Duplicate taps — identical tap payloads within a short window (~500 ms) may be dropped to avoid double events from rebuilds or pointer routing.