analytics library

Namespaced entrypoint for the refraction_ui analytics module — a headless, neutral Segment-spec collector/router (1:1 Dart port of @refraction-ui/analytics).

Import this file instead of package:refraction_ui/refraction_ui.dart when you need the analytics module's createConsoleSink. The package barrel hides createConsoleSink from the analytics export to avoid a collision with the telemetry module's flat-barrel createConsoleSink (telemetry owns the flat barrel). This entrypoint re-exports the full analytics public surface — including createConsoleSink — so there is no parity loss with the web library.

import 'package:refraction_ui/analytics.dart';

final analytics = createAnalytics(const AnalyticsConfig(
  app: 'my-app',
  env: 'production',
  endpoint: 'https://collect.example.com',
  writeKey: 'WRITE_KEY',
));
final sink = createConsoleSink();

If you need both modules' console sinks in one library, import the telemetry createConsoleSink from the package barrel and use this file's createConsoleSink with a prefix (e.g. import '...analytics.dart' as analytics;).

Classes

Analytics: The public analytics surface returned by createAnalytics.
AnalyticsConfig: createAnalytics configuration.
AnalyticsContext: The context block attached to every event. library identifies the collector; app/env identify the product instance. Free-form additions are contributed by with(context) children via extra.
AnalyticsEvent: The canonical Segment envelope. Every sink receives events in exactly this shape; the built-in HTTP sink ships it verbatim over the wire contract.
AnalyticsLibrary: Library identity stamped into AnalyticsContext.library.
AnalyticsPage: Page block attached to an event when a navigation context is available.
AnalyticsSink: Sink SPI — implemented by adapter packages (GA4, Azure, PostHog) and by the built-in HTTP sink. A sink declares the consent categories it requires; the router will not deliver to a sink whose categories are not all granted.
AnalyticsStorage: Cross-platform persistence SPI. The default picks platform storage (web localStorage / IO file) internally — invisible to the consumer.
CallOptions: Options accepted by every top-level call.
Consent: Consent gate. Mirrors createConsent from @refraction-ui/analytics.
ConsentApi: Consent gate runtime API.
ConsentConfig: Consent gate configuration.
ConsoleSink
HttpSink: The built-in Segment-spec HTTP sink.
HttpSinkOptions: Built-in HTTP sink options (Segment HTTP Tracking API wire contract).
HttpTransport: HTTP transport SPI — the built-in HTTP sink talks to this, never to a concrete client. The default resolves a platform transport (dart:io / browser) via conditional import — platform difference is internal.
Identity: Identity engine. Mirrors createIdentity from @refraction-ui/analytics.
IdentityConfig: Identity engine configuration.
IdentityStitch: A previous→current identity stitch pair (for alias).
MemoryStorage: Volatile per-process store (no-persistence fallback).
NoopAnalytics
Redactor: Build a key matcher from the deny-list + extra keys. extra entries match exactly (case-insensitive, normalised); deny-list entries match as substrings.
Session: Session engine. Mirrors createSession from @refraction-ui/analytics.
SessionApi: Session runtime API.
SessionConfig: Session engine configuration.
SinkDeliverContext: Context handed to every sink.deliver.
SinkInitContext: Context handed to sink.init.

Enums

AnalyticsEventType: Canonical Segment event types.

Extensions

AnalyticsEventTypeWire on AnalyticsEventType: Wire name for an AnalyticsEventType (matches the TS string union).

Constants

defaultSessionTimeoutMs → const int: GA4 parity: 30 minutes of inactivity ends a session.
kSchemaVersion → const int: Schema version stamped onto every envelope and the wire contract path.
piiDenyList → const List<String>: Built-in PII deny-list (substring, case-insensitive, separator-insensitive).
piiExactKeys → const List<String>: Keys that are PII only as an exact (normalised) match.
redacted → const String: Replacement token written in place of a redacted value.

Properties

uuidV4Re → RegExp: RFC 4122 v4 shape matcher (case-insensitive).
final

Functions

campaignFingerprint(String? search) → String?: Derive a stable campaign fingerprint from a URL's query string. A change in this fingerprint (a new campaign, not its absence) forces a new session, matching GA4's "campaign change resets the session" behaviour.
createAnalytics(AnalyticsConfig config) → Analytics: createAnalytics — the neutral Segment-spec collector/router. Returns the entire public Analytics surface. When enabled: false, a noop is returned and the live collector code does not run.
createConsoleSink({AnalyticsLogger? logger, List<String>? consentCategories}) → AnalyticsSink: Create the built-in dev-preset console sink.
createHttpSink(HttpSinkOptions options) → AnalyticsSink: Create the built-in Segment-spec HTTP sink.
createMemoryStorage() → AnalyticsStorage: Construct an in-memory store.
createNoopAnalytics() → Analytics: The noop collector returned when enabled: false.
isUuidV4(Object? value) → bool: True when value is a well-formed v4 UUID.
resolveStorage([AnalyticsStorage? override]) → AnalyticsStorage: Resolve the default storage for the current platform. A caller-supplied storage always wins. Falls back to in-memory when no durable platform store is reachable.
uuidv4([Random? random]) → String: Generate an RFC 4122 v4 UUID.

Typedefs

AnalyticsLogger = void Function(String message): Logger SPI (defaults to print). Injectable for tests / custom routing.
AnalyticsProperties = Map<String, Object?>: Arbitrary, JSON-serialisable bag of values.

analytics library

Classes

Enums

Extensions

Constants

Properties

Functions

Typedefs

refraction_ui package

analytics library