legacy_analytics library

The legacy behavioral-analytics event taxonomy: the wire envelope, its app context, the reserved-key and clock-skew helpers, the event registry, and the wire enums.

Deliberately kept out of the default restage_shared.dart barrel. This vocabulary is retained only for the legacy analytics runtime the SDK still ships; the replacement measurement contracts live in package:restage_measurement_schema/restage_measurement_schema.dart and are what new code should reach for. This entrypoint is removed together with that runtime.

Importing it opts in to a surface that is going away, so import it directly and only where the legacy runtime is being served.

Classes

AnalyticsAppContext

Client app context attached to a client-sourced AnalyticsEvent.

AnalyticsEvent

The behavioral-analytics event envelope every surface emits.

AnalyticsEventSpec

The registry entry for a canonical event name.

AnalyticsPlatform

Reporting platform carried in AnalyticsAppContext. Wire string, unknown-preserving — the known set is informational.

AnalyticsSource

Who produced an event. Server-stamped — never read from a client envelope. A public-key ingest path stamps client; only an internal / secret-key path may stamp server.

AnalyticsSurface

The surface that emitted an event. Wire string, unknown-preserving.

AnalyticsTier

Sampling tier. Server-derived from the taxonomy registry — never read from a client envelope (a client must not force tier1 past sampling).

Constants

kFlowLifecycleAnalyticsEventNames → const Set<String>

Lifecycle event names whose meaning requires a flow-shaped artifact.

kMaxEventSkew → const Duration

The maximum tolerated difference between a client's reported event time and the server receive time. Generous (48h) for legitimately offline-batched events while still bounding clock abuse.

kReservedPropertyKeys → const Set<String>

Reserved property keys.

kSurfaceArtifactFetchFailedEventName → const String

The canonical name for "a delivery resolved but its content never arrived".

Properties

kAnalyticsRegistry → Map<String, AnalyticsEventSpec>

The single-sourced event taxonomy: canonical name → {tier, requiredProperties}. Read by the SDK (warn on unknown), the ingest validator (derive tier), and the schema docs — the validator==SDK triangle.

final

Functions

clampOccurredAt({required DateTime clientOccurredAt, required DateTime receivedAt, Duration maxSkew = kMaxEventSkew}) → DateTime

Clamps an untrusted clientOccurredAt against the server-trusted receivedAt. Never drops the event — a stale/future time is bounded, and the raw value is preserved separately by the caller.

containsReservedKey(Map<String, Object?> properties) → bool

Whether properties contains any reserved (render-context) key.

isAnalyticsEventEligibleForArtifact({required String eventName, String? sourceKind, String? payloadKind}) → bool

Whether eventName is eligible for the supplied published artifact shape.

isRegisteredAnalyticsEvent(String name) → bool

Whether name is an explicitly-registered event (false for a soft-allowed unknown).

lookupAnalyticsEvent(String name) → AnalyticsEventSpec

Resolves name to its spec, soft-allowing an unknown name as a Tier-1 event with no required properties (never null, never a throw).

scrubReservedKeys(Map<String, Object?> properties) → Map<String, Object?>

Returns a new map with top-level namespaces and retired property keys removed. Retired property keys are removed at every map depth.

tierForEvent(String name) → String

The (server-derived) tier for name.