What Update Policies Are
Update policies control when an available OTA bundle should be downloaded and applied after your app checks for updates.
They are most commonly used with BundleDrop.init, which owns the startup flow for you.
Watch the same compatible v42 release reach three sample devices. The manual device illustrates calls made by the app; the policy does not trigger those actions itself.
One release, three update policies
App lifecycle walkthrough- Startup
- Download
- Ready to apply
- Activation
The same v42 activates by cold launch, immediate reload, or an explicit app call. A staged manual update can also activate at cold launch.
Available Policies
Bundle Drop supports three policies:
manualon-next-launchimmediate
manual
manual means Bundle Drop does not automatically download or apply updates. It is also the default — if you call BundleDrop.init without a policy, the runtime starts in manual and waits for your app to trigger update actions.
This is the best fit when you want a user-driven update flow, such as a settings screen or an update prompt with explicit buttons.
Teams usually pair this with useBundleDrop.
checkLatest() only checks availability. downloadUpdate() downloads and stages a bundle without reloading the current session; applyUpdate() activates the staged bundle by restarting the React Native runtime. A staged bundle can also activate on a later cold launch, so decide when your app calls downloadUpdate() if activation timing matters.
on-next-launch
on-next-launch means Bundle Drop downloads the update when it is available, stages it, and waits until the next cold app launch to apply it. Returning to an app that is still running is not a cold launch.
This is a good default when you want an automated flow without reloading the app immediately in the middle of a session.
immediate
immediate means Bundle Drop downloads the update and applies it as soon as possible.
This is useful when you want updates to take effect right away, but it is also the most aggressive option because it can interrupt the current session.
How This Fits with BundleDrop.init
BundleDrop.init is the main place where update policies matter.
It runs the automated startup flow and uses the selected policy to decide what should happen when a new update is available:
manual: initialize runtime state, but do not automatically download or applyon-next-launch: download now, apply on the next cold app launchimmediate: download now, apply right away
Choosing the Right Policy
A practical way to choose:
- use
manualfor user-controlled update UX - use
on-next-launchfor most production apps - use
immediatewhen you want the fastest possible update adoption
Dashboard Rollback and Safety Recovery
Dashboard rollback stops a release from being offered on a channel. On the next update check, an eligible compatible replacement follows the selected policy: your app controls manual activation, on-next-launch stages it for the next launch, and immediate applies it after download.
Safety recovery is separate. If a revoked current bundle has no safe compatible OTA replacement, Bundle Drop can recover to the embedded bundle even with manual or a check-only startup flow. Native integrity and compatibility checks also remain active.
Automatic Recovery handles repeatedly unhealthy OTA startups on a later cold launch. Its rollback.healthCheckMode setting controls when startup becomes healthy; it does not change your update policy.
Related Docs
- For the startup controller, see BundleDrop.init.
- For manual update flows, see useBundleDrop.
- For reverting a bad release, see Rollback.
- For on-device startup protection, see Automatic Recovery.