Skip to main content

Mandatory Updates

Mandatory updates force users to install an update before they can continue using the app. Use them for critical security fixes or breaking API changes.

Use sparingly

A broken mandatory update locks users out of your app entirely. Always test on a staging channel first.

Step 1: Publish a Mandatory Update​

Via CLI​

swiftpatch deploy -p ios --hermes --mandatory -n "Critical security fix"

Via Dashboard​

Step 1: Create a new release.

Step 2: Check Mandatory Update.

Step 3: Publish.

Step 2: Handle It in Your App​

Block the UI until the update is applied:

import React from 'react';
import { Modal, View, Text, Button, ActivityIndicator } from 'react-native';
import { useSwiftPatch, UpdateStatus } from '@swiftpatch/react-native';

function MandatoryUpdateScreen() {
  const { availableUpdate, status, downloadProgress, downloadUpdate, restart } = useSwiftPatch();

  if (!availableUpdate?.isMandatory) return null;

  return (
    <Modal visible animationType="fade">
      <View style={{ flex: 1, justifyContent: 'center', padding: 24 }}>
        <Text style={{ fontSize: 24, fontWeight: 'bold', textAlign: 'center' }}>
          Update Required
        </Text>
        <Text style={{ textAlign: 'center', marginVertical: 16, color: '#666' }}>
          A critical update is available. Please update to continue.
        </Text>

        {status === UpdateStatus.UPDATE_AVAILABLE && (
          <Button title="Update Now" onPress={downloadUpdate} />
        )}
        {status === UpdateStatus.DOWNLOADING && (
          <View style={{ alignItems: 'center' }}>
            <ActivityIndicator size="large" />
            <Text style={{ marginTop: 12 }}>
              Downloading... {downloadProgress?.percentage}%
            </Text>
          </View>
        )}
        {status === UpdateStatus.RESTART_REQUIRED && (
          <Button title="Restart" onPress={restart} />
        )}
      </View>
    </Modal>
  );
}

Best Practices​

  • Use sparingly -- only for critical security fixes or breaking API changes
  • Explain why the update is required in the UI
  • Show progress during download so users know something is happening
  • Test thoroughly -- a broken mandatory update locks users out
  • Test on staging first before publishing to production
danger

A broken mandatory update prevents users from accessing your app. There is no way to recover except publishing a fixed update or a new app store binary. Always test on a staging deployment first.