How Events Flow Through Processors

The processor pipeline¶

When you call TelemetryDeck.event(...), the event passes through a pipeline of processors before transmission. Each processor can inspect, enrich, transform, or filter the event.

graph TD
    A["TelemetryDeck.event(...)"] --> B[PreviewFilter]
    B --> C[DefaultParameters]
    C --> D[DefaultPrefix]
    D --> E[Validation]
    E --> F[TestMode]
    F --> G[UserIdentifier]
    G --> H[SessionTracking]
    H --> I[Device]
    I --> J[AppInfo]
    J --> K[Locale]
    K --> L[Calendar]
    L --> M[Accessibility]
    M --> N[TrialConversion]
    N --> O[Finalizer]
    O --> P[Event Cache]
    P --> Q[HTTP Transmitter]

Each processor receives two things:

• EventInput — the event name, parameters, and optional float value
• EventContext — mutable metadata that accumulates as the event moves through the pipeline (session ID, user identifier, test mode flag, and additional parameters)

A processor can modify either of these, then call next to pass control to the next processor. It can also throw ProcessorError.eventFiltered to silently drop the event.

At the end of the pipeline, the finalizer merges everything into a single Event object, hashes the user identifier with SHA256, and hands it to the cache for transmission.

Built-in processors¶

The SDK ships with a default set of processors. They run in this order:

PreviewFilterProcessor¶

Detects Xcode SwiftUI previews and drops all events during preview rendering. You never see preview noise in your dashboard.

DefaultParametersProcessor¶

Injects the defaultParameters you provided at initialization. These appear on every event. Your per-event parameters override them if keys collide.

DefaultPrefixProcessor¶

Prepends the eventPrefix to event names and parameterPrefix to custom parameter keys. SDK-internal parameters (prefixed with TelemetryDeck.) are not affected.

For example, with eventPrefix: "MyApp.", calling event("login") produces MyApp.login.

ValidationProcessor¶

Warns in the console if your event names or parameter keys collide with reserved TelemetryDeck.* names. Events pass through unchanged.

TestModeProcessor¶

Determines whether the event should be marked as test data. In DEBUG builds, test mode is on by default. You can override this with the testMode parameter during initialization.

UserIdentifierProcessor¶

Attaches a user identifier to the event context. The SDK auto-resolves a default identifier per platform (IDFV on iOS, a persisted UUID on macOS). You can override it with TelemetryDeck.setUserIdentifier(_:) or pass a customUserID per event. See User Identification for full details on resolution order, platform behavior, and hashing.

SessionTrackingProcessor¶

Manages session lifecycle and retention metrics. It:

• Generates a session ID at startup
• Starts a new session when the app returns from background after 5+ minutes
• Fires TelemetryDeck.Session.started on each new session (configurable)
• Detects first-ever launch and fires TelemetryDeck.Acquisition.newInstallDetected
• Adds retention parameters to every event:

Session history is persisted for 90 days. Older sessions are counted but their details are pruned.

DeviceProcessor¶

Adds hardware and platform information:

AppInfoProcessor¶

Adds app and SDK version information:

LocaleProcessor¶

Adds language and region preferences:

CalendarProcessor¶

Adds temporal context for time-based analysis:

AccessibilityProcessor¶

Captures accessibility settings and display properties. Results are cached for 1 hour to avoid excessive main-thread access.

TrialConversionProcessor¶

Available on iOS 15, macCatalyst 15, macOS 12, tvOS 15, and watchOS 8. Monitors StoreKit Transaction.updates in the background and automatically fires TelemetryDeck.Purchase.convertedFromTrial when a user transitions from a free trial to a paid subscription. No setup required — it runs silently.

Event caching and transmission¶

After processing, events land in a persistent cache (up to 10,000 events). The transmitter sends batched events every 10 seconds to {apiBaseURL}/v2/namespace/{namespace}/.

If transmission fails, the SDK retries with exponential backoff (doubling the interval, capped at 5 minutes). Events that receive permanent HTTP errors (400, 401, 403, 404, 413, 422, 501, 505) are dropped immediately.

You can force an immediate flush:

await TelemetryDeck.flush()

Pre-initialization buffering¶

Events sent before initialize() completes are buffered in memory and replayed once initialization finishes. Event ordering is preserved.