> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Over-the-air Updates

> Push fixes and improvements to live users without a store review. Users get the new version the next time they open the app.

Once your app is on the App Store and Play Store, most updates do not need to go through review again. The agent ships an instant update  the new code is published to a CDN, and the next time a user opens your app it downloads the change in the background and applies it on the next launch. You go from "fix typed" to "users see the fix" in under a minute.

## What ships instantly vs what needs a store review

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e6fafb', 'primaryTextColor': '#1a1a2e', 'primaryBorderColor': '#01b7cb', 'lineColor': '#01b7cb', 'fontFamily': 'Inter, sans-serif', 'fontSize': '14px' }}}%%
flowchart TB
    A{What changed?} -->|Copy, colors, layout, screen logic, fixes| B("Instant update"):::ota
    A -->|New permission, new device feature, app icon, version bump| C("New store build + review"):::store
    classDef ota fill:#e6fafb,stroke:#01b7cb,stroke-width:2px,rx:12,ry:12,color:#1a1a2e
    classDef store fill:#fff4e6,stroke:#e6a72b,stroke-width:2px,rx:12,ry:12,color:#1a1a2e
```

<CardGroup cols={2}>
  <Card title="Ships instantly" icon="zap">
    Copy changes, color tweaks, layout fixes, new screens, bug fixes, business logic, content updates, A/B test variants, paywall pricing rendered from a remote config.
  </Card>

  <Card title="Needs a new store build" icon="alert-triangle">
    Adding a new permission (camera, location, notifications), enabling a new device feature, updating the app icon or splash screen, changing the app's name, bumping the visible version number.
  </Card>
</CardGroup>

<Note>
  Both Apple and Google explicitly allow this kind of update for the code parts of your app. What they prohibit is changing core functionality or evading review  for example, swapping your photo app into a casino. The agent stays well clear of that line.
</Note>

## Ship an update

<Steps>
  <Step title="Make the change in chat">
    Ask for the change as you would for any edit  copy, colors, a new screen, a bug fix. The agent applies it in your preview and you confirm on your phone.
  </Step>

  <Step title="Click Update">
    In the top-right Ship menu, click **Update**. A panel opens asking which audience to target:

    * **All users on production** (default for most updates)
    * **Preview testers** (TestFlight + Play internal) to validate before going wide
    * **A specific staged rollout** (10%, 25%, 50%, 100%)
  </Step>

  <Step title="Confirm and publish">
    The agent packages the change and publishes it. Within seconds, your users' phones can pick up the new version on next launch.

    The chat shows: build hash, target channel, size of the update, estimated rollout time.
  </Step>
</Steps>

## How users get it

The next time a user opens your app, it checks for an update in the background while the splash screen is showing. If one is available and small (most are under 200 KB), it downloads silently and is applied on the next cold start. The user does not see anything different until that moment  no banner, no nag, no "please wait while we update".

<Tip>
  For changes the user should see immediately (a critical bug fix or a launched feature), ask the agent to enable **download now, apply now**: the update downloads on the current launch and reloads the app once it is ready. A short branded loading screen covers the swap.
</Tip>

## Staged rollouts

For changes that touch a lot of users (a redesign, a checkout flow, a paywall), roll the update out gradually so you catch problems before they hit everyone.

<Steps>
  <Step title="Pick a starting percentage">
    Open the Update panel and set the rollout to 10% or 25%. The agent assigns users to the new version randomly but consistently  the same user always sees the same version on every launch.
  </Step>

  <Step title="Watch the metrics">
    The chat surfaces live numbers: crash rate, app start time, error count, and any custom event you flag. If the new version regresses a metric by more than your threshold, the agent warns you.
  </Step>

  <Step title="Promote to 100%">
    Click **Expand rollout** to move to 50%, then 100%. Each step is reversible until you commit.
  </Step>
</Steps>

## Rollback

If something goes wrong, you can revert to the previous version in under 30 seconds.

<Steps>
  <Step title="Open the Updates history">
    In the chat or the project dashboard, every shipped update is listed with its hash, ship time, and the percentage of users on it.
  </Step>

  <Step title="Click Rollback">
    The agent re-publishes the previous good version with the rollback flag set. The new active version becomes the previous one. Existing users on the bad version get the rollback on next launch  no app store involvement.
  </Step>

  <Step title="Diagnose and reship">
    Fix the issue in chat, then update again. Rollbacks do not count against any limit.
  </Step>
</Steps>

<Warning>
  Rollback only works for changes that ship over-the-air. If the bad change was bundled into a store build (a new permission, a new device feature), you cannot roll back over-the-air  you must ship a fresh store build.
</Warning>

## Channels

Every app has three channels by default. They map to your build types.

| Channel       | Audience                                 | When updates land                       |
| ------------- | ---------------------------------------- | --------------------------------------- |
| `development` | The QR-code preview on your phone        | Immediately, on every change            |
| `preview`     | TestFlight + Play internal testers       | When you ship a preview build           |
| `production`  | Everyone who has the app from the stores | When you publish an over-the-air update |

Each channel is independent: a fix on preview does not touch production users until you explicitly promote it.

<Tip>
  Need an extra channel for power users or beta testers? Ask the agent to add one. Common patterns: `internal` for your own team's devices, `enterprise` for a single big customer who wants a slightly different build.
</Tip>

## Forcing an update

Sometimes you need every user on the new version right away  a security fix, a paywall change, a deprecation of an old API. Two patterns:

<CardGroup cols={2}>
  <Card title="Soft force" icon="bell">
    The app shows a dismissable banner asking the user to relaunch. The next cold start picks up the update. Most users dismiss and update within 24 hours.
  </Card>

  <Card title="Hard force" icon="lock">
    The app shows a blocking screen with a single "Update now" button. Tapping it reloads with the new version. Use sparingly  blocking screens hurt your store rating.
  </Card>
</CardGroup>

Ask the agent for either: *force everyone onto the latest update with a soft banner*.

## What you cannot ship over-the-air

The line between "instant update" and "store build required" is set by Apple, Google, and the runtime  not by Runable.

* **A new permission.** Adding camera, location, or contacts access requires a fresh build because the permission strings live in the app metadata.
* **A new device feature.** Push notifications, biometric unlock, Live Activities, NFC, or any other native capability that was not in the previous build.
* **A new app icon, splash screen, or display name.** All three live in the app metadata.
* **A version-number bump.** The user-visible version number can only change in a store build.
* **A different bundle identifier.** That is effectively a new app.
* **Anything that violates store guidelines.** Apple and Google both audit over-the-air updates and will pull apps that abuse the channel.

If a change you want would need a store build, the agent tells you up front and offers to run one instead.

## Next steps

<CardGroup cols={2}>
  <Card title="Deploy to App Store & Play Store" icon="rocket" href="/deploy-to-app-store-and-play-store">
    Run a fresh production build when an update needs a store review.
  </Card>

  <Card title="Environment Variables" icon="key" href="/mobile-app-environment-variables">
    Configure the values your app reads at runtime  no need to rebuild to change them.
  </Card>

  <Card title="Analytics" icon="bar-chart-3" href="/mobile-app-analytics">
    Watch crash rate, errors, and key events while a rollout is in progress.
  </Card>

  <Card title="Push Notifications" icon="bell" href="/mobile-app-push-notifications">
    Pair an over-the-air change with a push to let users know what is new.
  </Card>
</CardGroup>