# Update prompt & install timing

Choose, per release, **when** an update applies and whether the app **asks the user first**.

| Setting | What the user sees |
|---|---|
| Next launch (default) | Nothing. The update downloads in the background and runs the next time the app starts. |
| When the user comes back | Nothing. The update applies when the user returns to the app, optionally only after being away for a while (for example 5 minutes). The app reloads in about a second. |
| Right away (mandatory) | The app reloads at a safe moment as a [live patch](/live-patch), keeping the state you registered. |
| Ask the user first | An "Update available" dialog with your release notes, an **Update now** button and a **Later** button. Required updates have no Later. |

"Ask the user first" works together with any of the timings. If a user picks Later, a downloaded update still
applies on the next launch.

## 1. Add the prompt to your app

Mount `<UpdatePrompt />` once, near the root, **instead of** calling `sync()` yourself. It checks for
updates when it mounts and when the app returns to the foreground (at most once a minute):

```tsx
import { KillSwitchGate, UpdatePrompt } from "react-native-healkite";

export default function App() {
  return (
    <KillSwitchGate>
      {/* your app */}
      <UpdatePrompt />
    </KillSwitchGate>
  );
}
```

Releases you don't mark "Ask the user" still install silently, so you can mount the prompt now and use it
only when it matters (a big redesign, a change people should know about).

### Options

| Prop | Default | |
|---|---|---|
| `all` | `false` | Ask for **every** update, not only releases marked "Ask the user" |
| `askBeforeDownload` | `false` | Ask first and download only if the user agrees. By default the update downloads first, so tapping Update is instant. |
| `title`, `message`, `mandatoryMessage` | English defaults | Dialog text |
| `updateLabel`, `laterLabel` | "Update now", "Later" | Button labels |
| `showReleaseNotes` | `true` | Show the release description under "What's new" |
| `accentColor` | black (white in dark mode) | Main button colour |
| `checkOnMount`, `checkOnResume` | `true` | When to check |
| `render` | | Your own UI (see below) |

The dialog follows the system light/dark mode.

### Your own UI

`useUpdate()` gives you the update and the actions; render whatever fits your app (a banner, a bottom
sheet, a badge in settings):

```tsx
import { useUpdate } from "react-native-healkite";

function UpdateBanner() {
  const { update, phase, install, later } = useUpdate();
  if (!update) return null;
  return (
    <Banner
      title={update.mandatory ? "Update required" : "New version ready"}
      body={update.description}
      busy={phase === "downloading" || phase === "applying"}
      onAccept={install}
      onDismiss={update.mandatory ? undefined : later}
    />
  );
}
```

| Field | |
|---|---|
| `update` | `{ label, description, mandatory, size, sha256 }`, or `null` when there's nothing to ask about |
| `phase` | `idle`, `available` (not downloaded yet), `ready` (downloaded), `downloading`, `applying`, `error` |
| `install()` | Downloads if needed and applies now. Preserved state is kept ([live patch](/live-patch)). |
| `later()` | Hides it for this session. A downloaded update applies on the next launch. |
| `check()` | Check now |

Use `<UpdatePrompt render={(u) => …} />` to keep the automatic checks with your own UI.

## 2. Choose per release

From the CLI:

```sh
# ask the user first
npx healkite release -c production-… -p ios -r 2.4 --prompt -d "New checkout"

# apply when the user comes back after at least 5 minutes away
npx healkite release -c production-… -p ios -r 2.4 --on-reopen 5m

# change a published release
npx healkite patch rel_… --prompt false --on-reopen off
```

In the dashboard, open a release and press **Change** next to **Install**. Changes reach devices the next
time they check for updates.

## In code

`sync()` takes the same timings. A mode passed here wins over the release's setting and skips the prompt:

```ts
Healkite.sync({ installMode: "onBackground", minBackgroundSec: 300 });
Healkite.sync({ installMode: "immediate" }); // live patch now
```

| `installMode` | Applies |
|---|---|
| `"nextLaunch"` | Next start |
| `"onBackground"` | When the user returns after at least `minBackgroundSec` seconds away |
| `"immediate"` | Now, at a safe moment (see `holdLivePatch()`) |

## Notes

- Mandatory releases always apply right away. With "Ask the user first" they show the prompt without Later.
- Releases sent to specific devices use the next-launch timing (the prompt setting still applies).
- Apps on SDK versions before 0.4 ignore both settings and install on the next launch as before.
- Coming from CodePush? `updateDialog` works as it did, see [Migrate from CodePush](/migrate-from-codepush).
