> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Feature telemetry

> Opt-in decision, exposure, and outcome telemetry with bounded privacy and failure behavior

# Feature telemetry

Telemetry is optional and asynchronous. It cannot change evaluation results,
block a flag read, or consume configuration-sync quota.

## Event meanings

| Event      | Meaning                                                           | Not proof of                      |
| ---------- | ----------------------------------------------------------------- | --------------------------------- |
| Decision   | The evaluator returned details for one flag lookup                | The user saw the feature          |
| Assignment | An eligible unit mapped to a variation in an experiment iteration | Exposure or conversion            |
| Exposure   | Application code actually read/encountered the assigned feature   | A successful outcome              |
| Outcome    | A configured metric revision observed a binary or numeric value   | General-purpose product analytics |

Initialization, config download, cache refresh, hook mount, and assignment alone
are not exposures.

## Enable hosted delivery

<Tabs>
  <Tab title="React">
    ```tsx theme={null}
    <SuperflagProvider
      clientKey={clientKey}
      targetingKey={user.id}
      telemetry={{ hosted: true }}
    >
      <App />
    </SuperflagProvider>
    ```
  </Tab>

  <Tab title="React Native and Expo">
    ```tsx theme={null}
    <SuperflagProvider
      clientKey={clientKey}
      targetingKey={user.id}
      telemetry={{ hosted: true }}
    >
      <App />
    </SuperflagProvider>
    ```
  </Tab>
</Tabs>

Use a custom transport or `onEvent` callback when Superflag-hosted ingestion is
not desired.

## Track an outcome

```ts theme={null}
await client.track("new-checkout", "checkout-conversion")
await client.track("new-checkout", "checkout-revenue", 129.99)
```

Omitting the value records a binary conversion. Numeric values must be finite.
Tracking requires a current identity and a prior real exposure for the flag.
Each explicit call creates its own outcome; SDKs do not deduplicate conversions
or invent an attribution window.

## Privacy boundary

Canonical events contain pseudonymous subjects, bounded SDK metadata, decision
provenance, and only allow-listed dimensions. Raw targeting keys, evaluation
context, credentials, evaluated values, IP addresses, and user agents are not
stored as event fields.

Public-client events are always untrusted. The server derives app/environment
scope from the authenticated key, verifies client visibility, and applies
separate abuse controls. Public-only data cannot automatically mutate a flag or
declare a winner.

Raw accepted events retain for 30 days. Compact idempotency receipts retain for
35 days so a delayed retry cannot recreate an expired event. Subject erasure is
management-only: it deletes attributable retained data asynchronously and
leaves a tenant-keyed tombstone for the lateness window so delayed/offline
events at or before the erasure cutoff remain suppressed. The status route
returns a non-identifying receipt rather than the subject.

Raw export is a separate management-only signed-webhook sink with bounded
30-day backfill and delivery diagnostics. Data already delivered to a customer
destination cannot be recalled by Superflag erasure; destination operators must
apply their own retention and erasure policy.

## Delivery and retry

React and React Native use bounded queues with batching, item-level retry,
backpressure, explicit flush/shutdown, diagnostics, and once-per-iteration
exposure deduplication. React Native can persist accepted queue entries through
AsyncStorage. Evaluation does not import, await, or depend on delivery.

Hosted ingestion accepts up to 100 canonical events per batch with per-item
accepted, duplicate, permanent-error, or retryable-error results. Retry only
retryable items and preserve their event IDs.

<Info>
  Telemetry accounting is separate from config-sync quota and does not introduce
  MAU or DAU pricing.
</Info>