Upwell

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

EventWhenFields (besides the common ones)
checkA check completed. Throttled checks that return the current decision don't countdecision (kind), reason, policy (fresh, cached or none), durationMs
prompt_shownThe decision calls for a store prompt (recommended or required): once per decision kind and target per sessiondecision, reason, flow, target
prompt_actionThe user acted on a store promptaction, decision, target
store_flowA store flow finishedflow, result
ota_downloadedAn OTA update finished downloadingnewUpdateId
ota_appliedA restart into the downloaded OTA update was requestednewUpdateId, applyMode
updated_seenThe "Updated" sheet was closed, or markUpdateSeen() calledreleaseId
errorAnything passed to onErrorcontext, message

Details:

  • prompt_shown fires when the decision becomes store.recommended or store.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 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. 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).

Common fields

Every event also has:

Field
timestampEpoch ms
sdkVersionThe upwell package version
platformios or android
appVersion, buildversionName / CFBundleShortVersionString, and versionCode / CFBundleVersion
runtimeVersion, updateIdThe OTA runtime, and the running update (null for the embedded bundle)
installSourceplay, appStore, testFlight, sideload or unknown
installationIdRandom per-install id generated by the native module; a reinstall gets a new one
simulationThe 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 DESC

Stranded 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 DAY

A 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 DESC

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

On this page