# RNForge In-App Updates

Source: https://rnforge.dev/docs/in-app-updates

# Overview (/docs/in-app-updates)



Call `getUpdateStatus()` first, then start only the flows the current install supports.

The same status shape works for Play Store installs, debug builds, sideloaded installs, and iOS. Android can start Play Core update flows when they are available. Other installs return unavailable states, so your app can fall back to the store page.

## When To Use This [#when-to-use-this]

* Your Android app is distributed through Google Play and you need Play Core immediate or flexible update flows from JavaScript.
* For iOS, use the App Store page fallback to send users to the store.
* If you use Expo, this package needs a development build because Expo Go cannot load native modules.

## Support Matrix [#support-matrix]

| Platform                           | Update flow          | Store page          | Install listener       |
| ---------------------------------- | -------------------- | ------------------- | ---------------------- |
| Android installed from Google Play | Immediate + flexible | Yes                 | Yes                    |
| Android sideload/debug install     | Not available        | Play Store fallback | No                     |
| iOS                                | Not available        | App Store fallback  | Unsupported event only |

## Features [#features]

* Check update availability, current app version, and store version details.
* Start Android immediate updates when Play policy allows them.
* Start Android flexible updates, track download progress, and complete the downloaded update.
* Open the Play Store or App Store as a fallback.
* Handle unsupported devices, unsupported install sources, user cancellation, and missing store metadata as typed results.

## Public API [#public-api]

| Area                 | APIs                                                                             |
| -------------------- | -------------------------------------------------------------------------------- |
| Status               | `getUpdateStatus`, `isUpdateAvailable`                                           |
| Android update flows | `startImmediateUpdate`, `startFlexibleUpdate`, `completeFlexibleUpdate`          |
| Store fallback       | `openStorePage`, `canOpenStorePage`                                              |
| Flexible progress    | `addInstallStateListener`, `supportsInstallStateListener`                        |
| Flow guards          | `canStartImmediateUpdate`, `canStartFlexibleUpdate`, `canCompleteFlexibleUpdate` |

## Start Here [#start-here]

1. [Install the package](/docs/in-app-updates/install) and Nitro peer dependency.
2. Call `getUpdateStatus()` before starting any update flow.
3. Use helper functions like `canStartImmediateUpdate(status)` before starting a flow.
4. Use `openStorePage()` as the iOS and unsupported-install fallback.

See the [Quick Start](/docs/in-app-updates/quickstart) for copy-paste examples, [App Integration](/docs/in-app-updates/app-integration) for a full React component, the [API Guide](/docs/in-app-updates/api) for the status model and error handling, or [Troubleshooting](/docs/in-app-updates/troubleshooting) for common issues.


---

# Installation (/docs/in-app-updates/install)



## Install the package [#install-the-package]

### npm

```bash
    npm install @rnforge/react-native-in-app-updates react-native-nitro-modules
    ```

### pnpm

```bash
    pnpm add @rnforge/react-native-in-app-updates react-native-nitro-modules
    ```

### yarn

```bash
    yarn add @rnforge/react-native-in-app-updates react-native-nitro-modules
    ```

### bun

```bash
    bun add @rnforge/react-native-in-app-updates react-native-nitro-modules
    ```

## Rebuild the app [#rebuild-the-app]

This package includes native code. After installing it, rebuild the native app for the platform you use.

### Android [#android]

Rebuild the Android app from Android Studio or your React Native CLI workflow.

### iOS [#ios]

Install pods, then rebuild the iOS app from Xcode or your React Native CLI workflow.

```bash
cd ios && pod install
```

### Expo [#expo]

Expo Go cannot load this package because it includes native code. Use a development build.

```bash
npx expo prebuild
```

Then build and run the development app with your Expo workflow.

## Requirements [#requirements]

The package is built with Nitro and requires:

| Area          | Requirement                                              |
| ------------- | -------------------------------------------------------- |
| React Native  | Version supported by `react-native-nitro-modules`        |
| Native bridge | `react-native-nitro-modules`                             |
| Android       | `compileSdkVersion 34+`, NDK `27+`, Google Play Services |
| iOS           | Xcode `16.4+`, Swift `5.9+`                              |

## Platform Setup [#platform-setup]

### Android [#android-1]

No JavaScript setup is required after installation. The native module uses Google Play Core for real in-app update flows.

Real update flows require the app to be:

* installed from Google Play, not sideloaded or installed from a debug build
* signed with the same certificate as the Play track build
* running on a device with Google Play Services available
* built without legacy APK expansion (`.obb`) files

If those requirements are not met, APIs return typed unsupported results instead of pretending an update can run.

### iOS [#ios-1]

No additional setup is required. iOS does not support Google Play-style immediate or flexible in-app updates, so update-flow APIs return typed unsupported results.

Use `openStorePage({ ios: { appStoreId } })` to send users to the App Store.

## Verify Installation [#verify-installation]

After installing, call the API once to confirm the native module loads:

```typescript
import { getUpdateStatus } from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

console.log(status.platform);
console.log(status.supported);
console.log(status.reason);
```

On iOS without an App Store ID, `supported` is `false` and `reason` is `missing-app-store-id`. On Android debug or sideload installs, `supported` is usually `false` with `unsupported-install-source`. See [Troubleshooting](./troubleshooting) if the status does not match what you expect.


---

# Quick Start (/docs/in-app-updates/quickstart)



Use these examples when you want the shortest working snippets. For screen-level wiring, see [App Integration](./app-integration).

## Check Update Status [#check-update-status]

```typescript
import { getUpdateStatus, isUpdateAvailable } from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (!status.supported) {
  console.log('Updates are not supported:', status.reason);
} else if (isUpdateAvailable(status)) {
  console.log('Update available:', status.latestStoreVersion ?? status.latestStoreBuild);
} else {
  console.log('App is up to date');
}
```

## Immediate Update (Android Play) [#immediate-update-android-play]

```typescript
import {
  getUpdateStatus,
  startImmediateUpdate,
  canStartImmediateUpdate,
} from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (canStartImmediateUpdate(status)) {
  const result = await startImmediateUpdate();
  console.log('Immediate update result:', result.reason);
}
```

## Flexible Update (Android Play) [#flexible-update-android-play]

```typescript
import {
  getUpdateStatus,
  startFlexibleUpdate,
  completeFlexibleUpdate,
  addInstallStateListener,
  canStartFlexibleUpdate,
} from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (canStartFlexibleUpdate(status)) {
  let subscription: { remove: () => void } | undefined;

  subscription = addInstallStateListener((event) => {
    if (event.installStatus === 'downloading') {
      console.log('Download progress:', event.progress);
    }

    if (event.installStatus === 'downloaded') {
      console.log('Flexible update downloaded');
      void completeFlexibleUpdate().finally(() => {
        subscription?.remove();
      });
    }
  });

  try {
    const result = await startFlexibleUpdate();
    console.log('Flexible update result:', result.reason);
  } catch (error) {
    subscription.remove();
    throw error;
  }
}
```

Keep the subscription alive while the flexible download is active. In a React component, call `subscription.remove()` from your cleanup function when the screen unmounts.

## Store Page Fallback [#store-page-fallback]

```typescript
import {
  getUpdateStatus,
  openStorePage,
  canOpenStorePage,
} from '@rnforge/react-native-in-app-updates';

const storeOptions = {
  ios: {
    appStoreId: '1234567890',
    country: 'us',
  },
};

const status = await getUpdateStatus(storeOptions);

if (canOpenStorePage(status)) {
  await openStorePage(storeOptions);
}
```

Pass the same iOS options to both calls so the status and store fallback agree.

On Android, `openStorePage()` can be called without options. On iOS, `ios.appStoreId` is required.

## Common Helpers [#common-helpers]

| Helper                              | Use it when                                                  |
| ----------------------------------- | ------------------------------------------------------------ |
| `isUpdateAvailable(status)`         | You only need to know whether a newer version is available.  |
| `canStartImmediateUpdate(status)`   | You want to start the blocking Android Play update UI.       |
| `canStartFlexibleUpdate(status)`    | You want to start a background Android Play update download. |
| `canCompleteFlexibleUpdate(status)` | A flexible update has downloaded and can be installed.       |
| `canOpenStorePage(status)`          | You want a store-page fallback for unsupported update flows. |

See [App Integration](./app-integration) for a full React component example that combines these helpers.


---

# App Integration (/docs/in-app-updates/app-integration)



This example shows one React component that loads update status, starts immediate or flexible update flows, shows flexible download progress, and falls back to the store page when needed.

## InAppUpdatePanel [#inappupdatepanel]

```tsx
import React, { useCallback, useEffect, useRef, useState } from 'react';
import { Button, Text, View } from 'react-native';
import {
  addInstallStateListener,
  canOpenStorePage,
  canStartFlexibleUpdate,
  canStartImmediateUpdate,
  completeFlexibleUpdate,
  getUpdateStatus,
  InAppUpdatesError,
  openStorePage,
  startFlexibleUpdate,
  startImmediateUpdate,
} from '@rnforge/react-native-in-app-updates';
import type { InstallStateSubscription, UpdateStatus } from '@rnforge/react-native-in-app-updates';

const storeOptions = {
  ios: {
    appStoreId: '1234567890',
    country: 'us',
  },
};

export function InAppUpdatePanel() {
  const [status, setStatus] = useState<UpdateStatus | null>(null);
  const [loading, setLoading] = useState(false);
  const [message, setMessage] = useState<string | null>(null);
  const [progress, setProgress] = useState<number | null>(null);
  const subscriptionRef = useRef<InstallStateSubscription | null>(null);
  const completingRef = useRef(false);

  const loadStatus = useCallback(async () => {
    setLoading(true);
    setMessage(null);
    try {
      const next = await getUpdateStatus(storeOptions);
      setStatus(next);
    } catch (error) {
      if (error instanceof InAppUpdatesError) {
        setMessage(error.message);
      } else {
        setMessage('Unable to check for updates.');
      }
    } finally {
      setLoading(false);
    }
  }, []);

  useEffect(() => {
    void loadStatus();
    return () => {
      subscriptionRef.current?.remove();
      subscriptionRef.current = null;
    };
  }, [loadStatus]);

  const startImmediate = useCallback(async () => {
    if (!status || !canStartImmediateUpdate(status)) return;
    setLoading(true);
    setMessage(null);
    try {
      const next = await startImmediateUpdate();
      setStatus(next);
    } catch (error) {
      if (error instanceof InAppUpdatesError) {
        setMessage(error.message);
      } else {
        setMessage('Unable to start the update.');
      }
    } finally {
      setLoading(false);
    }
  }, [status]);

  const startFlexible = useCallback(async () => {
    if (!status || !canStartFlexibleUpdate(status)) return;
    setLoading(true);
    setMessage(null);

    subscriptionRef.current?.remove();
    subscriptionRef.current = null;
    completingRef.current = false;
    setProgress(null);

    subscriptionRef.current = addInstallStateListener((event) => {
      if (event.installStatus === 'downloading') {
        setProgress(event.progress ?? null);
      }

      if (event.installStatus === 'downloaded') {
        if (completingRef.current) return;
        completingRef.current = true;
        subscriptionRef.current?.remove();
        subscriptionRef.current = null;
        void completeFlexibleUpdate()
          .then((next) => {
            setStatus(next);
            setProgress(null);
          })
          .catch((error) => {
            completingRef.current = false;
            if (error instanceof InAppUpdatesError) {
              setMessage(error.message);
            } else {
              setMessage('Unable to complete the update.');
            }
          });
      }
    });

    try {
      const next = await startFlexibleUpdate();
      setStatus(next);
    } catch (error) {
      subscriptionRef.current?.remove();
      subscriptionRef.current = null;
      completingRef.current = false;
      setProgress(null);
      if (error instanceof InAppUpdatesError) {
        setMessage(error.message);
      } else {
        setMessage('Unable to start the download.');
      }
    } finally {
      setLoading(false);
    }
  }, [status]);

  const openStore = useCallback(async () => {
    if (!status || !canOpenStorePage(status)) return;
    setLoading(true);
    setMessage(null);
    try {
      await openStorePage(storeOptions);
    } catch (error) {
      if (error instanceof InAppUpdatesError) {
        setMessage(error.message);
      } else {
        setMessage('Unable to open the store.');
      }
    } finally {
      setLoading(false);
    }
  }, [status]);

  return (
    <View>
      <Text>Platform: {status?.platform ?? '...'}</Text>
      <Text>Supported: {status == null ? '...' : status.supported ? 'yes' : 'no'}</Text>
      <Text>
        Update available: {status == null ? '...' : status.updateAvailable == null ? 'unknown' : status.updateAvailable ? 'yes' : 'no'}
      </Text>
      {progress == null ? null : <Text>Download: {Math.round(progress * 100)}%</Text>}
      {status?.reason ? <Text>Reason: {status.reason}</Text> : null}
      {message ? <Text>{message}</Text> : null}

      <Button title="Check again" onPress={loadStatus} disabled={loading} />
      {status && canStartImmediateUpdate(status) ? (
        <Button title="Update now" onPress={startImmediate} disabled={loading} />
      ) : null}
      {status && canStartFlexibleUpdate(status) ? (
        <Button title="Download update" onPress={startFlexible} disabled={loading} />
      ) : null}
      {status && canOpenStorePage(status) ? (
        <Button title="Open store" onPress={openStore} disabled={loading} />
      ) : null}
    </View>
  );
}
```

## Notes [#notes]

* Check status before starting a flow. Use helper functions like `canStartImmediateUpdate` and `canStartFlexibleUpdate` to guard each action.
* Register the install-state listener before calling `startFlexibleUpdate()` so you receive events from the start.
* Clean up the listener on unmount to avoid stale callbacks.
* Complete a flexible update when the listener reports `event.installStatus === 'downloaded'`. The example removes the listener and uses `completingRef` so duplicate events do not start duplicate completion calls.
* If you refresh status separately and show a manual Complete update button, guard it with `canCompleteFlexibleUpdate(status)`.
* Use the store page fallback when an in-app update flow is not available.


---

# API Guide (/docs/in-app-updates/api)



## Capability-First Design [#capability-first-design]

Capability-first means checking what the current install can do before starting an update flow. Instead of checking `if (Platform.OS === 'android')`, you check what the current environment supports:

```typescript
import { getUpdateStatus } from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (status.capabilities.immediate) {
  // Immediate updates are supported
}

if (status.capabilities.flexible) {
  // Flexible updates are supported
}
```

This approach works because:

* iOS reports immediate and flexible update capabilities as `false`
* iOS can still report store-page and version-lookup capability when App Store options are provided
* Android installs that cannot run Play update flows report those flow capabilities as `false`
* Android Play installs report the update capabilities allowed by Play Core
* Your code works everywhere without platform checks

## Typed Results, Not Exceptions [#typed-results-not-exceptions]

Expected states are returned as **typed results**, not thrown exceptions:

```typescript
const status = await getUpdateStatus();

// Check if updates are supported
if (!status.supported) {
  console.log('Reason:', status.reason);
  // 'unsupported-platform' | 'unsupported-install-source' | etc.
} else if (status.updateAvailable) {
  console.log('Current:', status.currentVersion);
  console.log('Latest:', status.latestStoreVersion);
}
```

**Exceptions are only thrown for actual errors:**

* Invalid input (e.g., missing required options)
* Native bridge failures
* Native layer failures
* Unexpected runtime errors

## Update Status [#update-status]

The `UpdateStatus` object is the core of the API. It tells you:

**UpdateStatus**

```typescript
type UpdateStatus = {
  /** The host platform. */
  platform: Platform
  /** Whether in-app updates are supported on this device and install. */
  supported: boolean
  /** Whether a newer version is available in the store. `null` if unknown. */
  updateAvailable: boolean | null
  /** Capabilities reported by the current platform. */
  capabilities: Capabilities
  /** Which update flows are currently allowed to start. */
  allowed: AllowedFlows
  /** The reason describing the current availability or unsupported state. */
  reason: AvailabilityReason | UnsupportedReason
  /** The currently installed version string, if known. */
  currentVersion?: string
  /** The currently installed build number or version code, if known. */
  currentBuild?: string | number
  /** The latest version available in the store, if known. */
  latestStoreVersion?: string
  /** The latest build number or version code in the store, if known. */
  latestStoreBuild?: string | number
  /** The current install lifecycle status, if reported by the platform. */
  installStatus?: InstallStatus
  /** Android-specific details. Only present on Android. */
  android?: AndroidDetails
  /** iOS-specific details. Only present on iOS. */
  ios?: IosDetails
}
```

### Platform Support [#platform-support]

```typescript
status.supported        // boolean - are in-app updates supported?
status.reason           // string - why or why not
status.platform         // 'android' | 'ios'
```

### Update Availability [#update-availability]

```typescript
status.updateAvailable          // boolean | null
status.currentVersion           // string - installed version
status.latestStoreVersion       // string - latest in store
status.currentBuild             // string | number - installed build
status.latestStoreBuild         // string | number - latest build in store
```

### Capabilities [#capabilities]

**Capabilities**

```typescript
type Capabilities = {
  /** Whether immediate update flows are supported. */
  immediate: boolean
  /** Whether flexible update flows are supported. */
  flexible: boolean
  /** Whether opening the store page is supported. */
  storePage: boolean
  /** Whether the latest store version can be looked up. */
  latestVersionLookup: boolean
  /** Whether install-state listeners are available. */
  installStateListener: boolean
}
```

```typescript
status.capabilities.immediate           // boolean
status.capabilities.flexible            // boolean
status.capabilities.storePage           // boolean
status.capabilities.latestVersionLookup // boolean
status.capabilities.installStateListener // boolean
```

### Allowed Flows [#allowed-flows]

Even if a capability is supported, it might not be allowed right now:

**AllowedFlows**

```typescript
type AllowedFlows = {
  /** Whether an immediate update can be started now. */
  immediate: boolean
  /** Whether a flexible update can be started now. */
  flexible: boolean
}
```

```typescript
status.allowed.immediate  // boolean - can start immediate update now?
status.allowed.flexible   // boolean - can start flexible update now?
```

### Install Status [#install-status]

For flexible updates, track the installation lifecycle:

```typescript
status.installStatus
// 'unknown' | 'pending' | 'downloading' | 'downloaded' |
// 'installing' | 'installed' | 'failed' | 'canceled' | 'unsupported'
```

### Platform-Specific Details [#platform-specific-details]

```typescript
// Android details (only on Android)
status.android?.packageName
status.android?.playCore?.availableVersionCode
status.android?.playCore?.updatePriority

// iOS details (only on iOS)
status.ios?.bundleIdentifier
status.ios?.appStoreId
status.ios?.appStore?.version
status.ios?.appStore?.releaseNotes
```

## Immediate Updates [#immediate-updates]

Immediate updates show a blocking UI that forces the user to update before continuing:

```typescript
import {
  getUpdateStatus,
  startImmediateUpdate,
  canStartImmediateUpdate
} from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (canStartImmediateUpdate(status)) {
  try {
    const result = await startImmediateUpdate();
    // Update completed or app restarted
  } catch (error) {
    // Handle error (invalid-input, bridge-error, native-error, unexpected)
    console.error('Update failed:', error);
  }
}
```

**When to use immediate updates:**

* Critical security fixes
* Breaking API changes
* Mandatory feature updates

## Flexible Updates [#flexible-updates]

Flexible updates download in the background while the user continues using the app:

**InstallStateEvent**

```typescript
type InstallStateEvent = {
  /** The host platform. */
  platform: Platform
  /** Whether in-app updates are supported on this device and install. */
  supported: boolean
  /** The current install lifecycle status. */
  installStatus: InstallStatus
  /** The reason for this event. */
  reason: InstallStateEventReason
  /** Bytes downloaded so far, if reported. */
  bytesDownloaded?: number
  /** Total bytes to download, if reported. */
  totalBytesToDownload?: number
  /** Download progress as a fraction from 0 to 1, if computable. */
  progress?: number
  /** Error code string, if the event reports an error. */
  errorCode?: string
  /** Human-readable message, if provided by the platform. */
  message?: string
  /** Android-specific details. Only present on Android. */
  android?: AndroidDetails
}
```

```typescript
import {
  getUpdateStatus,
  startFlexibleUpdate,
  completeFlexibleUpdate,
  addInstallStateListener,
  canStartFlexibleUpdate,
} from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (canStartFlexibleUpdate(status)) {
  let subscription: { remove: () => void } | undefined;

  subscription = addInstallStateListener((event) => {
    if (event.installStatus === 'downloading') {
      const progress = event.progress ?? 0;
      console.log(`Downloaded: ${(progress * 100).toFixed(1)}%`);
    }

    if (event.installStatus === 'downloaded') {
      console.log('Update downloaded, installing');
      void completeFlexibleUpdate().finally(() => {
        subscription?.remove();
      });
    }
  });

  try {
    const result = await startFlexibleUpdate();
    console.log('Flexible update result:', result.reason);
  } catch (error) {
    subscription?.remove();
    throw error;
  }
}
```

**When to use flexible updates:**

* Non-critical feature updates
* Performance improvements
* UI enhancements
* When you want to avoid interrupting the user

## Store Page Fallback [#store-page-fallback]

If in-app updates aren't supported, you can still open the store page:

```typescript
import { openStorePage, canOpenStorePage, getUpdateStatus } from '@rnforge/react-native-in-app-updates';

const storeOptions = {
  ios: {
    appStoreId: '123456789',
    country: 'us',
  },
};

const status = await getUpdateStatus(storeOptions);

if (canOpenStorePage(status)) {
  try {
    await openStorePage(storeOptions);
    // Opens Play Store on Android or App Store on iOS.
  } catch (error) {
    console.error('Failed to open store:', error);
  }
}
```

On Android, `openStorePage()` can be called without options. On iOS, pass `ios.appStoreId` to both `getUpdateStatus()` and `openStorePage()` so the status result can report the store-page capability correctly.

## Error Handling [#error-handling]

Async functions that call the native module can throw `InAppUpdatesError`. Helper functions only read an `UpdateStatus` object.

| Code            | Meaning                                   |
| --------------- | ----------------------------------------- |
| `invalid-input` | Invalid options or arguments.             |
| `bridge-error`  | React Native bridge communication failed. |
| `native-error`  | Native layer reported a failure.          |
| `unexpected`    | Any other unexpected failure.             |

```typescript
import { InAppUpdatesError } from '@rnforge/react-native-in-app-updates';

try {
  await startImmediateUpdate();
} catch (error) {
  if (error instanceof InAppUpdatesError) {
    switch (error.code) {
      case 'invalid-input':
        // You passed invalid options
        console.error('Invalid input:', error.message);
        break;

      case 'bridge-error':
        // React Native bridge communication failed
        console.error('Bridge error:', error.message);
        break;

      case 'native-error':
        // Native layer reported an error
        console.error('Native error:', error.message);
        if (error.android) {
          console.error('Android details:', error.android);
        }
        break;

      case 'unexpected':
        // Something unexpected happened
        console.error('Unexpected error:', error.message);
        break;
    }
  } else {
    // Not an InAppUpdatesError
    throw error;
  }
}
```

## Helper Functions [#helper-functions]

The API provides helper functions to check status before acting:

```typescript
import {
  getUpdateStatus,
  isUpdateAvailable,
  canStartImmediateUpdate,
  canStartFlexibleUpdate,
  canCompleteFlexibleUpdate,
  canOpenStorePage,
  supportsInstallStateListener,
} from '@rnforge/react-native-in-app-updates';

const status = await getUpdateStatus();

if (isUpdateAvailable(status)) {
  console.log('Update available');
}

if (canStartImmediateUpdate(status)) {
  console.log('Can start immediate update');
}

if (canStartFlexibleUpdate(status)) {
  console.log('Can start flexible update');
}

if (canCompleteFlexibleUpdate(status)) {
  console.log('Can complete flexible update');
}

if (canOpenStorePage(status)) {
  console.log('Can open store page');
}

if (supportsInstallStateListener(status)) {
  console.log('Install state listener is supported');
}
```

These helpers check multiple conditions (support, capability, availability, allowed) so you don't have to.

## Platform Notes [#platform-notes]

### Android [#android]

* Requires Google Play Store (sideloaded apps report `unsupported-install-source`)
* Requires Google Play Services (devices without report `play-core-unavailable`)
* APK expansion files are not supported (`apk-expansion-files-unsupported`)
* Immediate updates may not be allowed during certain app states
* Flexible updates require calling `completeFlexibleUpdate()` to install

### iOS [#ios]

* Immediate and flexible update flows are **not supported**
* Store page opening requires `ios.appStoreId`
* Version lookup uses the App Store lookup API when `ios.appStoreId` is provided
* `getUpdateStatus()` can return `missing-app-store-id` when App Store lookup options are missing
* Use `openStorePage()` as the update mechanism

## Common Patterns [#common-patterns]

### Check for Update on App Start [#check-for-update-on-app-start]

```typescript
import { getUpdateStatus, isUpdateAvailable } from '@rnforge/react-native-in-app-updates';

async function checkForUpdate() {
  const status = await getUpdateStatus();

  if (!status.supported) {
    console.log('Updates not supported:', status.reason);
    return null;
  }

  if (!isUpdateAvailable(status)) {
    console.log('App is up to date');
    return null;
  }

  return {
    current: status.currentVersion,
    latest: status.latestStoreVersion,
    releaseNotes: status.ios?.appStore?.releaseNotes,
  };
}
```

### Progressive Update Flow [#progressive-update-flow]

A common pattern is to try immediate updates first for critical updates, fall back to flexible for non-critical updates, and use the store page as a last resort. See [App Integration](./app-integration) for a full React component that implements this fallback chain.

## Next Steps [#next-steps]

* Check the [Quick Start](./quickstart) for a minimal example
* Review the [Installation](./install) guide for setup instructions
* See [App Integration](./app-integration) for a full React component example
* See [Troubleshooting](./troubleshooting) for common issues and fixes


---

# Troubleshooting (/docs/in-app-updates/troubleshooting)



Most expected states come back as typed results on the status object, not thrown errors. If an API call throws, it is usually a native module setup problem or invalid input. This page covers the most common issues and how to fix them.

## Android says updates are not available [#android-says-updates-are-not-available]

Real Play update flows only work when the app is distributed through Google Play. Debug builds, sideloaded installs, and apps signed with a different certificate commonly return `unsupported-install-source`.

If the device does not have Google Play Services, the status may return `play-core-unavailable` instead.

These are expected results, not crashes. Show a fallback UI (such as the store page) instead of treating the unsupported status as an error.

## iOS returns missing-app-store-id [#ios-returns-missing-app-store-id]

iOS store lookup and store page opening need an App Store ID. Without one, `getUpdateStatus()` returns `supported: false` with reason `missing-app-store-id`.

Pass `ios.appStoreId` to both `getUpdateStatus()` and `openStorePage()`:

```typescript
const storeOptions = {
  ios: {
    appStoreId: '1234567890',
  },
};

const status = await getUpdateStatus(storeOptions);
await openStorePage(storeOptions);
```

## Native module is not found [#native-module-is-not-found]

This package includes native code. If the module is not found, rebuild the native app after installing.

1. **Android:** rebuild the Android app from Android Studio or your React Native CLI workflow.
2. **iOS:** run `cd ios && pod install`, then rebuild the iOS app from Xcode or your React Native CLI workflow.
3. **Expo:** use a development build. Run `npx expo prebuild`, then build and run the development app with your Expo workflow. Expo Go is not supported.

See [Installation](./install) for the full setup steps.

## Flexible update does not complete [#flexible-update-does-not-complete]

Call `completeFlexibleUpdate()` only after the download is ready. Do not call it immediately after `startFlexibleUpdate()`.

In the listener, check the event:

```typescript
if (event.installStatus === 'downloaded') {
  await completeFlexibleUpdate();
}
```

If you refresh status separately, you can also guard with `canCompleteFlexibleUpdate(status)`.

## Store page does not open [#store-page-does-not-open]

Check `canOpenStorePage(status)` before calling `openStorePage()`.

* On Android, the store page depends on the package being available in the Play Store.
* On iOS, `ios.appStoreId` is required. Without it, `openStorePage()` throws `InAppUpdatesError` with code `invalid-input`.

Invalid input, bridge failures, and native failures throw `InAppUpdatesError`. Check `error.code` to narrow the cause.

## The listener never fires [#the-listener-never-fires]

Register the listener before calling `startFlexibleUpdate()`. If you register it after, you may miss the download events.

Keep the subscription alive while the update downloads. In a React component, store the subscription in a ref and remove it in the cleanup function when the screen unmounts.

The listener is for flexible update progress. It does not fire for immediate updates.

## Testing with debug builds [#testing-with-debug-builds]

Debug and sideload builds are useful for testing fallback UI, error handling, and store page behavior.

Real Android update flows (immediate and flexible) must be validated with a Play-distributed build. Do not expect these flows to run in a normal debug install.