AppSessionTracker class

Session id, install/session counters, and foreground duration — one place every feature reads instead of each hand-rolling its own "first open"/"session count" bookkeeping.

One session per process: current is set once at construction (cold start) — sequence is persisted and incremented exactly once per construction, satisfying "cold start increments count exactly once" without any extra bookkeeping.

Foreground duration uses Stopwatch (real elapsed time), not nowMsClamped — a duration measurement doesn't care about wall-clock anomalies, only real elapsed time, and Stopwatch gives that directly. Time spent backgrounded is never added to it.

Resume policy: a resume that follows less than sessionTimeout of background time continues the same session (foreground duration keeps accumulating). A resume after longer than that starts a brand new session (new SessionInfo.sessionId, SessionInfo.sequence bumped, foreground duration reset) — the common "session timeout" convention most mobile analytics SDKs use.

Corrupt/negative sequence: a hand-edited or corrupted persisted sequence that reads negative is clamped to 0 before incrementing — never propagates a negative value forward, and a fresh cold start after corruption always reports at least sequence 1.

Consent gate: analyticsContext returns {} unless ConsentCategory.analytics is granted on the registered ConsentStateService (FEAT-61) — this tracker never sends anything itself, but a caller attaching this context to an analytics event must not leak session/install data before consent.

Inheritance
  • Object
  • GetLifeCycle
  • DisposableInterface
  • GetxService
  • AppSessionTracker

Constructors

AppSessionTracker({Duration sessionTimeout = const Duration(minutes: 30), RoyLifecycleCoordinator? lifecycle, String generateSessionId()?, Stopwatch createStopwatch()?})

Properties

current → SessionInfo
no setter
foregroundDuration → Duration
no setter
hashCode → int
The hash code for this object.
no setterinherited
initialized → bool
Checks whether the controller has already been initialized.
no setterinherited
isClosed → bool
Checks whether the controller has already been closed.
no setterinherited
onDelete → InternalFinalCallback<void>
Internal callback that starts the cycle of this controller.
finalinherited
onStart → InternalFinalCallback<void>
Called at the exact moment the widget is allocated in memory. It uses an internal "callable" type, to avoid any @overrides in subclases. This method should be internal and is required to define the lifetime cycle of the subclass.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sessionTimeout → Duration
final

Methods

$configureLifeCycle() → void
inherited
analyticsContext() → Map<String, Object?>
Session/install/foreground-duration context meant to be attached to an analytics event — returns {} unless analytics consent is currently granted (no registered ConsentStateService counts as not granted).
handleLifecycleEvent(RoyLifecycleEvent event) → void
Called by the registered RoyLifecycleCoordinator hook — exposed publicly (rather than private) so a caller without a coordinator can drive it directly, and so tests can too without standing up a full WidgetsBinding observer.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onClose() → void
Called before onDelete method. onClose might be used to dispose resources used by the controller. Like closing events, or streams before the controller is destroyed. Or dispose objects that can potentially create some memory leaks, like TextEditingControllers, AnimationControllers. Might be useful as well to persist some data on disk.
override
onInit() → void
Called immediately after the widget is allocated in memory. You might use this to initialize something for the controller.
inherited
onReady() → void
Called 1 frame after onInit(). It is the perfect place to enter navigation events, like snackbar, dialogs, or a new route, or async request.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

maybe → AppSessionTracker?
no setter