# Tracking plan and metric definitions

Track actual behavior explicitly. Send stable identifiers and put variations in properties. All metrics are scoped to an app and environment. Date boundaries are UTC; report API ranges use inclusive `from`, exclusive `to`. SDK initialization and typed examples are in the [React Native reference](sdk.md) and [Swift reference](swift-sdk.md). The wire events and all metric definitions are shared; platform-specific APIs do not redefine the reports.

## Identity and app opens

- `app_first_open` is automatic once per app/environment installation storage. It means the app opened with the SDK, not an App Store download. Reinstallation/storage clearing may create another installation.
- `app_active` is automatic on active initialization and foreground transitions when the React Native AppState adapter is supplied, or through the Swift SDK's default UIKit lifecycle adapter. Do not call track manually for lifecycle events. Navigation is not automatically tracked.
- `identify(opaqueAccountId)` links anonymous activity to an authenticated account. Reset on logout/account switching. Dashboard accounts are separate from these tracked users.
- New users are resolved distinct identities with a first-open event. App health active users require app-open events. DAU/WAU/MAU are unique openers over the trailing 1/7/30 UTC dates ending at each chart point. New means first opened within that same window; existing means first opened earlier. Missing first-open evidence remains unknown.
- Retention cohorts group users by first-open date. D1/D7/D14/D30 measure an app open on that exact return day. Incomplete days/cohorts are unavailable, not zero. Feature actions do not define app-open retention.

## First-class workflows

- `analytics.onboarding({id, version, steps})` defines ordered screens in code. Start, step, answer and complete helpers attach a persisted attempt and definition. Versions are positive integers; an omitted version is derived from the steps. Reusing a version with changed steps is rejected. The dashboard discovers definitions; no manual event registration is needed.
- Answers attach to a step/attempt and may be single/multiple choice. Percentages use respondents, so multi-select percentages can exceed 100% in total. See the SDK reference for exact method signatures.
- `analytics.paywall({id, version})` defines a design, while each presentation records its placement and current access state. One design can appear in onboarding, settings or a feature gate. Onboarding presentations carry the journey context; see [paywalls](paywalls.md).
- SDK purchase attempts capture intent/outcomes/transaction IDs. RevenueCat verifies trials/payments. Existing subscriber presentations are retained but excluded from new-subscription conversion. Unknown access is not silently treated as confirmed inactive.

## Business metrics

[New business](new-business.md) follows first-open cohorts: trials, direct payments, later trial payments and first-purchase revenue stay with the acquisition date. Recent trials remain pending until their outcome is known. [Revenue](revenue.md) follows transaction dates and includes renewals; it is not the same cohort calculation. RevenueCat provides observed billing and stored history/snapshots. Automatic setup attempts an initial bounded import; explicit refreshes can recover missed available events. New business uses both webhook and imported billing evidence with SDK identity/first-open matching; repeated transactions are counted once. Unknown amounts/history do not become invented totals. Read these report guides for denominators, refunds, subscription snapshots and limitations.

## Custom feature events and feedback

Use `track('workout_completed', {workout_type:'strength'})` for app-specific features. Count means occurrences; users means distinct identities that performed that event in the selected period; times per user divides occurrences by those performers, not all users. Properties provide categories/distributions. Built-in lifecycle, identity, onboarding and paywall events are excluded from the feature report.

Use `analytics.feedback({message, email?})` or the optional React Native FeedbackSheet for contact. Swift provides the feedback API for an app-owned form. Feedback is stored separately from events and never contributes to active users or conversions. Its inbox covers all dates but respects app/environment. See [feedback](feedback.md).

Avoid emails, message text, payment credentials and unnecessary personal data in analytics properties. Optional reply email belongs only in feedback. The SDK contract and report tests must agree with these definitions.

## Appbase website and SaaS telemetry

Appbase’s own optional PostHog measurement is a separate dataset with separate consent and opaque dashboard-account identity. Its initial setup funnel uses first observed workspace creation, not exact authentication signup. See [website analytics preferences](https://appbase.so/analytics); no mobile metric above is redefined by that instrumentation.

## Full-history reporting ranges

- Reports accept ordered UTC dates from 1970 onward; `to` stays exclusive. There is no 90-day report limit. All time starts at the earliest stored SDK event or RevenueCat billing event/purchase for the selected app/environment and ends tomorrow at 00:00 UTC. An empty app starts today. Importing older billing history can extend this range. “All time” does not imply a complete provider import.
- Daily and range-anchored 7-day intervals preserve existing behavior. Monthly/yearly intervals follow UTC calendar months/years; the first and last bucket are clipped to the selection. Unique feature/active users are counted within each bucket, never summed from daily unique counts. Revenue and first-open cohort outcomes keep their existing definitions.
- Charts use at most 800 daily/weekly/monthly points before selecting a coarser interval (up to yearly); the API returns the actual interval and retains the full selected range and totals.
- App health samples rolling DAU/WAU/30-day MAU on each bucket’s last day (today for an unfinished current bucket). Yearly is the chart sampling interval, not yearly active users. Retention remains exact-day retention with weekly first-open cohort rows, regardless of chart interval. Subscription charts similarly preserve their existing bucket-end snapshot semantics.