<!--
{
  "availability" : [
    "iOS: 27.0.0 -",
    "iPadOS: 27.0.0 -",
    "macCatalyst: -",
    "macOS: 27.0.0 -",
    "tvOS: 27.0.0 -",
    "visionOS: 27.0.0 -",
    "watchOS: 27.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "StateReporting",
  "identifier" : "/documentation/StateReporting/StateReporter",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "StateReporting"
    ],
    "preciseIdentifier" : "s:14StateReporting0A8ReporterC"
  },
  "title" : "StateReporter"
}
-->

# StateReporter

An object unique per domain that records state transitions and volatile metadata updates.

```
final class StateReporter<StableMetadata, VolatileMetadata> where StableMetadata : ReportableMetadata, VolatileMetadata : ReportableMetadata
```

## Overview

`StateReporter` is the central object for recording your feature’s or subsystem’s current
state. You obtain an instance through the [`reporter(for:stableMetadata:volatileMetadata:)`](/documentation/StateReporting/StateReporter/reporter(for:stableMetadata:volatileMetadata:))
method, which guarantees that every caller using the same domain string receives the same
object. Attempting to call the method with different generic type arguments for an
already-registered domain is a fatal error.

A state is uniquely identified by the combination of a label and stable metadata. A
transition to a new state occurs when either changes; reporting the same label and
stable metadata is a no-op. *Volatile metadata* provides additional context
within an ongoing state and is discarded when the next transition begins. Both stable
and volatile metadata are expressed as types conforming to [`ReportableMetadata`](/documentation/StateReporting/ReportableMetadata), which can be
synthesized automatically with the [`ReportableMetadata()`](/documentation/StateReporting/ReportableMetadata()) macro.

Call [`reportTransition(to:stableMetadata:volatileMetadata:)`](/documentation/StateReporting/StateReporter/reportTransition(to:stableMetadata:volatileMetadata:)) whenever your feature transitions
to a new state. Pass `nil` as the label to signal that no state is active. Call
[`reportVolatileMetadataUpdate(_:)`](/documentation/StateReporting/StateReporter/reportVolatileMetadataUpdate(_:)) to update volatile metadata without beginning a new state
transition. Calling either method more frequently than user interaction timescales can trigger
rate limiting, causing state updates to go unlogged.

```swift
let reporter = StateReporter.reporter(
    for: "com.example.myapp.checkout",
    stableMetadata:AppMetadata.self,
    volatileMetadata:SessionMetadata.self
)

reporter.reportTransition(
    to: "paymentSheet",
    stableMetadata: AppMetadata(userTier: .premium),
    volatileMetadata: SessionMetadata(cartTotal: 49.99)
)
```

For Objective-C, use [`SRStateReporter`](/documentation/StateReporting/SRStateReporter).

## Topics

### Instance Properties

[`let domain: String`](/documentation/StateReporting/StateReporter/domain)

The reverse DNS-style domain name that identifies this reporter.

### Instance Methods

[`func reportTransition(to: String?, stableMetadata: StableMetadata?, volatileMetadata: VolatileMetadata?)`](/documentation/StateReporting/StateReporter/reportTransition(to:stableMetadata:volatileMetadata:))

Reports a transition to a new state.

[`func reportVolatileMetadataUpdate(VolatileMetadata?)`](/documentation/StateReporting/StateReporter/reportVolatileMetadataUpdate(_:))

Updates the volatile metadata within the current state without beginning a new transition.

### Type Methods

[`static func reporter(for: String, stableMetadata: StableMetadata.Type, volatileMetadata: VolatileMetadata.Type) -> StateReporter<StableMetadata, VolatileMetadata>`](/documentation/StateReporting/StateReporter/reporter(for:stableMetadata:volatileMetadata:))

Returns the reporter instance unique to the given domain and metadata types.

## Relationships

### Conforms To

[`Sendable`](/documentation/Swift/Sendable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)