# Send update events to your analytics (/guides/analytics-events)

Upwell sends nothing anywhere itself. Instead, the controller emits typed events through `onEvent`:
every check, every store prompt and what the user did with it, store flows, OTA downloads and
restarts, and errors. Forward them to the analytics you already use with a few lines.

```tsx
<UpwellProvider
  policy={url}
  ota={expoUpdatesAdapter()}
  onEvent={(event) => analytics.track(`upwell_${event.type}`, event)}
>
```

The controller emits the events, not the UI kit, so they're the same with your own UI or
[without React](/docs/guides/without-react) (`createUpwell({ onEvent })`).

## Events [#events]

| Event | When | Fields (besides the common ones) |
| --- | --- | --- |
| `check` | A check completed. Throttled checks that return the current decision don't count | `decision` (kind), `reason`, `policy` (`fresh`, `cached` or `none`), `durationMs` |
| `prompt_shown` | The decision calls for a store prompt (recommended or required): once per decision kind and target per session | `decision`, `reason`, `flow`, `target` |
| `prompt_action` | The user acted on a store prompt | `action`, `decision`, `target` |
| `store_flow` | A store flow finished | `flow`, `result` |
| `ota_downloaded` | An OTA update finished downloading | `newUpdateId` |
| `ota_applied` | A restart into the downloaded OTA update was requested | `newUpdateId`, `applyMode` |
| `updated_seen` | The "Updated" sheet was closed, or `markUpdateSeen()` called | `releaseId` |
| `error` | Anything passed to [`onError`](/docs/guides/debugging-and-analytics#error-contexts) | `context`, `message` |

Details:

- **`prompt_shown`** fires when the decision becomes `store.recommended` or `store.required`. The
  [UI kit](/docs/reference/ui) shows its prompt for exactly those decisions; with your own UI, render
  the prompt for them too, or the event counts prompts nobody saw. It's also when Upwell counts a
  prompt against `maxPrompts`. A recommendation that escalates to required is reported again.
- **`prompt_action`** has `action: 'update'` when a store flow starts from the prompt
  (`startUpdate()`, `startStoreUpdate()`), `'later'` for `dismiss()` (snoozes the prompt), and
  `'dismiss'` when the user declines Google Play's own update dialog (also snoozes a recommendation).
  The App Store sheet doesn't say whether the user updated, so iOS only reports `update`.
- **`store_flow`** `result` is a [flow result](/docs/concepts/store-flows#flow-results). When a Play
  flow fails and Upwell falls back to the store link, both flows are reported.
- **`ota_applied`** `applyMode` is `prompt` when the user tapped restart, `immediate` when the policy
  restarted right away, and `null` when `applyOta()` was called outside an `ota.ready` decision.
  `nextLaunch` updates apply on their own at the next launch, without an event: the next `check`
  carries the new `updateId`.
- **`newUpdateId`** is the downloaded update's id when the OTA adapter reports one
  (`expoUpdatesAdapter()` does; see [OTA adapters](/docs/guides/custom-sources-and-adapters#ota-adapters)).

### Common fields [#common-fields]

Every event also has:

| Field | |
| --- | --- |
| `timestamp` | Epoch ms |
| `sdkVersion` | The `upwell` package version |
| `platform` | `ios` or `android` |
| `appVersion`, `build` | versionName / CFBundleShortVersionString, and versionCode / CFBundleVersion |
| `runtimeVersion`, `updateId` | The OTA runtime, and the running update (`null` for the embedded bundle) |
| `installSource` | `play`, `appStore`, `testFlight`, `sideload` or `unknown` |
| `installationId` | Random per-install id generated by the native module; a reinstall gets a new one |
| `simulation` | The [`simulate()`](/docs/guides/testing-and-simulation) scenario, or `null` on the real device |

The install fields are `null` until the device was read (for example in an `error` event when the
native module isn't linked).

Nothing personal: no device identifiers, no user ids. `installationId` lets you
count installs; drop it before sending if you don't want even that. Events from simulation have
`simulation` set: skip them, as the examples below do.

The types are exported as `UpwellEvent`, narrowed by `type`:

```ts
import type { UpwellEvent } from 'upwell';

function onEvent(event: UpwellEvent) {
  if (event.type === 'store_flow' && event.result === 'failed') {
    Sentry.addBreadcrumb({ category: 'upwell', message: `store flow ${event.flow} failed` });
  }
}
```

A handler that throws (or an `async` one that rejects) never breaks the update flow: the error goes
to `onError` with context `onEvent`.

## PostHog [#posthog]

With [`posthog-react-native`](https://posthog.com/docs/libraries/react-native):

```tsx
import PostHog from 'posthog-react-native';
import type { UpwellEvent } from 'upwell';

export const posthog = new PostHog('<project api key>', { host: 'https://us.i.posthog.com' });

export function sendToPostHog(event: UpwellEvent) {
  if (event.simulation) return;
  const { type, ...properties } = event;
  posthog.capture(`upwell_${type}`, properties);
}
```

```tsx
<UpwellProvider policy={url} ota={expoUpdatesAdapter()} onEvent={sendToPostHog}>
```

Nested properties (`target.build`) work in PostHog filters, breakdowns and SQL.

## Firebase Analytics [#firebase-analytics]

With [React Native Firebase](https://rnfirebase.io/analytics/usage). Firebase only takes flat
string and number parameters (string values up to 100 characters), and reserves some event names
(`error` among them), so prefix the names and flatten the fields:

```tsx
import { getAnalytics, logEvent } from '@react-native-firebase/analytics';
import type { UpwellEvent } from 'upwell';

export function sendToFirebase(event: UpwellEvent) {
  if (event.simulation) return;
  const { type, ...fields } = event;
  const params: Record<string, string | number> = {};
  for (const [key, value] of Object.entries(fields)) {
    if (value == null) continue;
    if (typeof value === 'object') {
      // target: { version, build } → target_version, target_build
      for (const [k, v] of Object.entries(value)) {
        if (v != null) params[`${snake(key)}_${k}`] = String(v);
      }
    } else {
      params[snake(key)] = typeof value === 'number' ? value : String(value).slice(0, 100);
    }
  }
  void logEvent(getAnalytics(), `upwell_${type}`, params);
}

const snake = (key: string) => key.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
```

```tsx
<UpwellProvider policy={url} ota={expoUpdatesAdapter()} onEvent={sendToFirebase}>
```

To break reports down by a parameter (`build`, `reason`, `target_build`), register it as a custom
dimension in Google Analytics first.

## Other tools [#other-tools]

Amplitude, Mixpanel, Segment and the rest all take an event name and a properties object, like
PostHog. For Sentry, turn events into breadcrumbs so crash reports show what Upwell was doing:

```ts
onEvent={(event) =>
  Sentry.addBreadcrumb({ category: 'upwell', message: event.type, data: event })
}
```

## Volume [#volume]

`check` fires on every launch and every foreground check (at most once per `minCheckIntervalMs`,
60 seconds by default). The other events are rare. If `check` is too many events for your plan,
send it once a day per install, or sample it; the dashboards below only need the latest check per
install.

## Dashboards worth building [#dashboards-worth-building]

The examples use [PostHog SQL](https://posthog.com/docs/sql) with the event names above; build the
same thing with your tool's insights or a BigQuery export.

### Installs per build [#installs-per-build]

How many installs run each build and OTA update: your real adoption curve, and the input for
raising `minimum` safely.

```sql
SELECT properties.build, properties.updateId, count(DISTINCT properties.installationId) AS installs
FROM events
WHERE event = 'upwell_check' AND timestamp > now() - INTERVAL 7 DAY
GROUP BY properties.build, properties.updateId
ORDER BY installs DESC
```

### Stranded share [#stranded-share]

The share of installs on a runtime that no longer gets OTA updates (needs a policy with
`ota.latestRuntimeVersion`; see [Stranded installs](/docs/concepts/stranded-installs)). When it's
high, consider `strandedRequireAfterDays`.

```sql
SELECT
  count(DISTINCT if(properties.reason = 'stranded', properties.installationId, NULL))
    / count(DISTINCT properties.installationId) AS stranded_share
FROM events
WHERE event = 'upwell_check' AND timestamp > now() - INTERVAL 1 DAY
```

A short window keeps installs that updated during it from counting as stranded.

### Prompt conversion [#prompt-conversion]

A funnel per target build: `upwell_prompt_shown` → `upwell_prompt_action` with `action = 'update'`
→ `upwell_store_flow` with `result` `accepted` or `opened` → `upwell_check` with `build` equal to
the target. Break it down by `decision` and `reason` to compare soft and forced prompts, and watch
`later` and `dismiss` rates when you change copy (`message`) or `recommendAfterDays`.

```sql
SELECT
  properties.target.build AS target,
  countIf(event = 'upwell_prompt_shown') AS shown,
  countIf(event = 'upwell_prompt_action' AND properties.action = 'update') AS updated,
  countIf(event = 'upwell_prompt_action' AND properties.action != 'update') AS later
FROM events
WHERE event IN ('upwell_prompt_shown', 'upwell_prompt_action')
  AND properties.decision = 'store.recommended'
  AND timestamp > now() - INTERVAL 30 DAY
GROUP BY target
ORDER BY target DESC
```

Also useful: OTA adoption (`ota_downloaded`, then a `check` whose `updateId` is the `newUpdateId`),
store flow failures by `flow`, and errors by `context`.
