OSGAccountServer/docs/ANALYTICS_METRICS_DICTIONARY.md

# OSGKeyboard product analytics metrics dictionary

This document is the canonical definition of product metrics. All dates and
cohorts use UTC calendar boundaries. Counts are based on distinct accounts when
an installation is linked, otherwise on the pseudonymous installation.

Admin presets cover exactly 7, 30, or 90 UTC calendar dates, starting at 00:00
on the first date and ending at the current instant. The current UTC date is
therefore explicitly partial.

## North-star metric

### Weekly AI active users (WAIU)

The number of distinct users that successfully complete at least one AI feature
during a UTC calendar week.

- Managed AI and ASR use server-settled `credit_usage_records`.
- Local and BYOK use accepted `AI_FEATURE_SUCCEEDED` client events.
- Managed client success events provide feature breakdowns but are not added to
  the server-settled total, preventing double counting.
- Week-over-week growth is `(current WAIU - previous WAIU) / previous WAIU`.
  A missing previous population is reported without a percentage.

## Growth and activation

### New installations

Distinct installations whose first accepted `FIRST_OPEN` event occurred in the
selected period. Acquisition channel is fixed by the first non-`UNKNOWN`
channel observed for the installation.

Allowed channels:

- `APP_STORE_ORGANIC`
- `REFERRAL`
- `SOCIAL_CONTENT`
- `UNKNOWN`

### New accounts

Accounts whose `accounts.created_at` falls in the selected period.

### 24-hour AI activation rate

The percentage of new installations that have completed their full 24-hour
observation window and successfully complete any AI feature within 24 hours of
their first open. Unmatured installations are excluded from both numerator and
denominator. Managed usage before that installation's first open is ignored.

### Time to first value

Elapsed time from `FIRST_OPEN` to the first successful AI feature. The dashboard
reports the median in minutes. Users without a successful AI feature are not
included in the median and remain visible in the activation denominator.

### 24-hour growth funnel

A strict cohort of installations with a completed 24-hour observation window:
first open, account registration after first open, first AI value event after
registration, and first server-verified purchase after that value event. Every
downstream step must occur within 24 hours of first open. D7 belongs only to the
retention report and is not mixed into this funnel.

## Activity

### AI DAU, WAU and MAU

Distinct value-active users in the last 1, 7 and 30 UTC days ending at the
report's `until` timestamp.

### DAU/MAU stickiness

`AI DAU / AI MAU`. The value is null when MAU is zero.

### Successful AI requests

The sum of settled managed requests and successful local/BYOK client events.
Managed client success events are excluded from this total.

### Successful AI requests per active user

`successful AI requests / distinct value-active users` for the selected period.

### Registered product-active users

The operations overview counts distinct registered accounts with either a
successful AI value event (managed, local, or BYOK) or a finalized manual
keyboard-input summary in the selected period. The displayed rate divides this
population by all registered accounts.

## Keyboard input usage

Keyboard input metrics use finalized UTC-day summaries produced on-device.
They describe manually committed OSGKeyboard text only and are independent
from AI value events, billing and referral qualification.

### Keyboard input active users

Distinct account identities, falling back to pseudonymous installations, with
at least one accepted keyboard usage summary in the selected UTC-date window.

### Activation-to-input conversion

Keyboard input active users divided by distinct identities with either a
`KEYBOARD_ACTIVATED` event or an accepted keyboard usage summary in the same
UTC-date window. Including summary-only identities prevents missing activation
telemetry from producing rates above 100%.

### Chinese, English and bilingual active users

- Chinese active: at least one committed Han-script character.
- English active: at least one committed Latin letter.
- Bilingual active: both Chinese and English counts are non-zero.

These populations overlap and must not be summed.

### Character volume and language share

Character volume is the sum of client-classified Chinese, English and other
committed characters. Chinese and English share use only classified language
characters as the denominator:

- Chinese share: `Chinese / (Chinese + English)`.
- English share: `English / (Chinese + English)`.

Both shares are unavailable when the denominator is zero. Other characters
remain visible in total volume but do not dilute the language split.

### Input sessions

An input session is a keyboard activation containing at least one manually
committed character. Chinese-only, English-only, mixed-language and other-only
session counts form a complete partition. Average characters per input session
is `total committed characters / input sessions`.

## Retention

The cohort date is the UTC date of a user's first successful AI feature.
Retention is value retention, not application-open retention.

- `D1`: active on cohort date + 1 day.
- `D7`: active on cohort date + 7 days.
- `D30`: active on cohort date + 30 days.

Each retention rate uses the original cohort size as denominator. A day that has
not fully elapsed at the report's `until` timestamp is returned as unavailable,
not zero. Channel and first-feature breakdowns are optional dimensions and must
not alter the base cohort definition.

## AI feature usage

Allowed feature types:

- `TRANSCRIPTION`
- `POLISH`
- `AI_ASSISTANT`
- `AGENT`
- `HOTWORD`
- `OTHER`

Allowed execution modes:

- `MANAGED`
- `LOCAL`
- `BYOK`

Feature distributions use accepted client events because server billing only
distinguishes `ASR` and `LLM`. Server-settled aggregates remain authoritative
for managed totals, credits, token counts and ASR duration.

## Credit consumption

### Daily total credit consumption

The sum of non-negative `credit_usage_records.charged_credits` by UTC date.

### Average daily credits per AI active user

For each UTC date, divide total settled credits by distinct managed AI users,
then average those daily values across days containing at least one active user.

### Median user-day credits

The median of per-account daily settled credits. This is shown beside the mean
to prevent a small number of heavy users from distorting typical consumption.

### Average credits per managed request

`settled credits / settled managed requests`. Local and BYOK events consume no
server credits and are excluded.

## Monetization

### 7-day and 30-day free-to-paid conversion

The percentage of newly registered accounts with a first credited StoreKit
purchase no later than 7 or 30 days after registration. The selected report
period filters when each observation window matures: a 7-day report cohort uses
registrations shifted exactly 7 days earlier, and the 30-day cohort is shifted
30 days earlier. This keeps every denominator fully observed and makes the rate
available even when the selected preset is no longer than the conversion window.

### Paying users

Distinct accounts with at least one credited StoreKit purchase in the period.

### Repeat purchase rate

The percentage of paying accounts with at least two credited StoreKit purchases
across their lifetime.

### Purchase intent funnel

A strict installation cohort: `PURCHASE_VIEWED`, followed by
`PURCHASE_STARTED`, followed by a StoreKit purchase verified by the server for
the linked account. Each event must occur after the previous step and before the
report's `until`. `PURCHASE_CANCELLED` is a separate signal, not a funnel step.

StoreKit transaction count and granted credits are operational proxies. Net
revenue, App Store commission and refunds require App Store financial data and
are outside this service's first version.

## Referral funnel

The ordered cohort contains bindings created in the selected period:

1. Referral binding created.
2. The same invitee reaches an AI value event after binding.
3. The same binding is rewarded before the report's `until`.

`REFERRAL_SHARED` distinct installations and invitation opens are independent
directional signals. Invitation opens combine accepted `INVITE_OPENED` events
with anonymous first-party page-view counters, so they are not people and must
never be placed in the ordered conversion funnel.

Pending and ineligible bindings are parallel status counts, not sequential
funnel steps.

## Experience guardrails

- AI success rate: successful client AI completions divided by starts with a
  terminal success or failure event.
- Managed request failure rate: terminal non-settled `provider_requests` divided
  by terminal managed requests.
- Client latency: successful and failed terminal events grouped by declared
  duration bucket. Exact P50/P95 values are not inferred from buckets.
- Credit-blocked users: distinct installations reporting
  `INSUFFICIENT_CREDITS` during the period.

Guardrails are diagnostic and never count as value-active events.