Core
Core API
The ReleaseHealth API: init options, markHealthy, onRollbackRecommended, notifyReload, and the useReleaseHealth hook with its status values.
Everything the host app touches lives on the ReleaseHealth object plus the useReleaseHealth
hook, both from react-native-release-health. The engine is pure TypeScript; the adapters and
sinks feed it.
ReleaseHealth.init(options)
Starts the engine. Call once, as early as possible.
| Option | Default | Description |
|---|---|---|
adapter | required | Your OTA vendor integration (OtaAdapter) |
sinks | [] | Where events go; the state machine runs regardless |
healthyTimeoutMs | 15000 | Deadline for markHealthy() after a fresh update launches |
crashLoopThreshold | 2 | Consecutive failed launches before the update is declared failed. The default fires on the second launch, after one crashed launch |
autoRollback | false | Run adapter.rollback() automatically on a failed verdict, where the adapter supports it |
cohort | none | Rollout cohort label attached to session_start |
ReleaseHealth.markHealthy()
Closes the probation window for the active update. Call it when your first screen is genuinely interactive: data loaded, navigation responsive. Calling it from a splash screen defeats the purpose. See Getting started for placement.
ReleaseHealth.onRollbackRecommended(cb)
Subscribes to failed-update verdicts. Fires with { updateId, reason } where reason is
'crash-loop' or 'apply-failed'. Returns an unsubscribe function.
const unsubscribe = ReleaseHealth.onRollbackRecommended(({ updateId, reason }) => {
// Disable the release server-side, page on-call, or rely on autoRollback.
});ReleaseHealth.notifyReload()
Tell the engine you are about to intentionally reload, for example applying a downloaded update
with Updates.reloadAsync() or HotUpdater.reload(). A reload during probation restarts the
probation timer instead of counting as a failed launch. Omit it and an intentional reload is
indistinguishable from a crash.
ReleaseHealth.notifyReload();
await Updates.reloadAsync();useReleaseHealth()
React hook returning { status, activeUpdateId, nativeVersion, buildNumber, cohort } and
re-rendering on every transition.
const { status, activeUpdateId } = useReleaseHealth();Statuses
| Status | Meaning |
|---|---|
starting | The engine is initializing |
stable | Running the embedded bundle, or an update that was already accepted |
probation | A fresh update is waiting for markHealthy() |
healthy | markHealthy() was accepted within the window |
suspect | The probation timeout elapsed without markHealthy(), not yet failed |
failed | Crash loop or apply failure; rollback recommended |
The contract on your side
markHealthy()placement is load-bearing. Interactive, not merely rendered.- Intentional reloads must be announced with
notifyReload()before a same-session reload. - Development builds are excluded.
__DEV__short-circuits probation, so verify with release builds. - One pending update at a time. A newer
update_downloadedoverwrites the pending marker; if you ship faster than users relaunch, only the newest update is on probation.
Full detail on each of these is in Limitations.
Extending the engine
Adapters and sinks implement small interfaces you can write yourself. The contracts, and the built-in implementations, are on the Packages and contracts page.