Teardown | Kill Old App Versions Instantly. Ship Without Fear. Build Boldly.

The Force Update client automatically checks your app version against your configured release policy and can require users to update.

Overview

Force updates work by:

Checking app version on identify
Checking again when app returns to foreground
Emitting status changes your app can respond to

Version Status

type VersionStatus =
  | { type: 'initializing' }   // SDK starting up
  | { type: 'checking' }       // Version check in progress
  | { type: 'up_to_date' }     // Current version is valid
  | { type: 'update_available' }   // Optional update exists
  | { type: 'update_recommended' } // Recommended update exists
  | { type: 'update_required' }    // Must update to continue
  | { type: 'disabled' }       // Version/build has been disabled

Basic Usage

Using the Hook

import { useForceUpdate } from '@teardown/react-native';

function App() {
  const { versionStatus, isUpdateRequired, isUpdateAvailable, isUpdateRecommended } = useForceUpdate();

  if (isUpdateRequired) {
    return <ForceUpdateModal />;
  }

  if (isUpdateRecommended) {
    return (
      <>
        <UpdateBanner onDismiss={() => {}} />
        <MainApp />
      </>
    );
  }

  return <MainApp />;
}

Hook Return Values

interface UseForceUpdateResult {
  versionStatus: VersionStatus;      // Full status object
  isUpdateAvailable: boolean;        // Any update exists (available, recommended, or required)
  isUpdateRecommended: boolean;      // Update is recommended but not required
  isUpdateRequired: boolean;         // Update is mandatory
}

Configuration

Configure force update behavior in TeardownCore:

const teardown = new TeardownCore({
  // ...other options
  forceUpdate: {
    checkIntervalMs: 300_000,        // 5 minutes (default)
    checkOnForeground: true,         // Check when app foregrounds (default: true)
    identifyAnonymousDevice: false,  // Check even when not identified (default: false)
  },
});

Options

Option	Type	Default	Description
`checkIntervalMs`	number	300000	Minimum time between version checks. Use `0` for every foreground, `-1` to disable. Values below 30s are clamped to 30s.
`checkOnForeground`	boolean	true	Check version when app returns to foreground
`identifyAnonymousDevice`	boolean	false	Check version even when user is not identified

Direct API Access

Get Current Status

const status = core.forceUpdate.getVersionStatus();

const unsubscribe = core.forceUpdate.onVersionStatusChange((status) => {
  if (status.type === 'update_required') {
    // Show force update modal
  }
});

// Cleanup
unsubscribe();

Implementation Patterns

function ForceUpdateModal() {
  const handleUpdate = () => {
    // Open app store
    Linking.openURL('https://apps.apple.com/app/your-app');
  };

  return (
    <Modal visible>
      <View style={styles.container}>
        <Text>Update Required</Text>
        <Text>Please update to continue using the app.</Text>
        <Button onPress={handleUpdate} title="Update Now" />
      </View>
    </Modal>
  );
}

function UpdateBanner({ onDismiss }: { onDismiss: () => void }) {
  const { isUpdateRecommended } = useForceUpdate();

  if (!isUpdateRecommended) return null;

  return (
    <View style={styles.banner}>
      <Text>A new version is available</Text>
      <Button onPress={onDismiss} title="Later" />
      <Button onPress={() => Linking.openURL('...')} title="Update" />
    </View>
  );
}

Root Level Guard

function RootLayout() {
  const { isUpdateRequired } = useForceUpdate();

  if (isUpdateRequired) {
    return <ForceUpdateScreen />;
  }

  return <Stack />;
}

How It Works

On Identify - Version status is returned from the identify API
On Foreground - If checkOnForeground is true and interval has passed, re-identifies to check version
State Persistence - Last known status is cached for offline access
Event Emission - Status changes trigger subscribers and hook re-renders

Dashboard Configuration

Configure version policies in the Teardown Dashboard:

Go to your project settings
Navigate to "Releases" or "Version Management"
Set policies for each version/build:
- Active - Version is valid
- Update Available - Optional update exists
- Update Recommended - Soft nudge to update
- Update Required - Force update
- Disabled - Version blocked entirely

Force Updates