Send update events to your analytics
Forward Upwell's update events to PostHog, Firebase Analytics or anything else, and the dashboards worth building.
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.
<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 (createUpwell({ onEvent })).
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 | context, message |
Details:
prompt_shownfires when the decision becomesstore.recommendedorstore.required. The UI kit 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 againstmaxPrompts. A recommendation that escalates to required is reported again.prompt_actionhasaction: 'update'when a store flow starts from the prompt (startUpdate(),startStoreUpdate()),'later'fordismiss()(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 reportsupdate.store_flowresultis a flow result. When a Play flow fails and Upwell falls back to the store link, both flows are reported.ota_appliedapplyModeispromptwhen the user tapped restart,immediatewhen the policy restarted right away, andnullwhenapplyOta()was called outside anota.readydecision.nextLaunchupdates apply on their own at the next launch, without an event: the nextcheckcarries the newupdateId.newUpdateIdis the downloaded update's id when the OTA adapter reports one (expoUpdatesAdapter()does; see OTA adapters).
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() 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:
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
With posthog-react-native:
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);
}<UpwellProvider policy={url} ota={expoUpdatesAdapter()} onEvent={sendToPostHog}>Nested properties (target.build) work in PostHog filters, breakdowns and SQL.
Firebase Analytics
With React Native Firebase. 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:
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()}`);<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
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:
onEvent={(event) =>
Sentry.addBreadcrumb({ category: 'upwell', message: event.type, data: event })
}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
The examples use PostHog SQL with the event names above; build the same thing with your tool's insights or a BigQuery export.
Installs per build
How many installs run each build and OTA update: your real adoption curve, and the input for
raising minimum safely.
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 DESCStranded share
The share of installs on a runtime that no longer gets OTA updates (needs a policy with
ota.latestRuntimeVersion; see Stranded installs). When it's
high, consider strandedRequireAfterDays.
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 DAYA short window keeps installs that updated during it from counting as stranded.
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.
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 DESCAlso useful: OTA adoption (ota_downloaded, then a check whose updateId is the newUpdateId),
store flow failures by flow, and errors by context.