Configuration

SwiftPatch works with zero configuration. Set your App ID in native config, wrap your app, and you're shipping OTA updates.

Step 1: Add Your App ID

iOS -- Info.plist:

ios/YourApp/Info.plist

<key>SwiftPatchAppId</key>
<string>YOUR_APP_ID</string>

Android -- strings.xml:

android/app/src/main/res/values/strings.xml

<string name="SwiftPatchAppId">YOUR_APP_ID</string>

tip

Find your App ID in the dashboard under Settings > General.

Step 2: Wrap Your App

App.tsx

import { withSwiftPatch } from '@swiftpatch/react-native';

function App() {
  return <YourApp />;
}

export default withSwiftPatch(App);

The SDK automatically checks for updates on launch and resume, downloads them in the background, and applies them when the user next resumes the app.

---

Basic Options

App.tsx

export default withSwiftPatch(App, {
  deploymentKey: 'dk_xxx',
  debug: __DEV__,
  onUpdate: (update) => {
    console.log('New deploy available:', update);
  },
});

Option	Type	Default	Description
deploymentKey	string	From native config	Override the deployment key. Useful for switching channels at runtime.
debug	boolean	false	Enable verbose SDK logging. Set to __DEV__ for dev-only logging.
onUpdate	(update: ReleaseInfo) => void	undefined	Callback when a new deployment is available.

Smart Defaults

Behavior	Default	What it does
Install mode	ON_NEXT_RESUME	Updates apply when the user returns from the background.
Check interval	0 (every resume)	Checks for updates on every resume.
Auto-stabilize	After 2 launches	New bundle promoted to "stable" after 2 crash-free launches.
Crash detection	10s window, 2 crashes	Rolls back automatically if 2 crashes happen within 10 seconds.

---

Deployment Keys

Deployment keys control which channel your app receives updates from (e.g., Production vs. Staging).

Option A -- Native config (recommended):

ios/YourApp/Info.plist

<key>SwiftPatchDeploymentKey</key>
<string>dk_your_production_key</string>

Option B -- Runtime override:

App.tsx

export default withSwiftPatch(App, {
  deploymentKey: isInternalTester ? 'dk_staging_key' : 'dk_production_key',
});

warning

Store deployment keys in environment variables or a secrets manager, not in source control.

---

Advanced Configuration

You probably don't need this

The defaults work well for most apps. Only change these if you have a specific requirement.

App.tsx — full example

import { withSwiftPatch, InstallMode } from '@swiftpatch/react-native';

export default withSwiftPatch(App, {
  deploymentKey: 'dk_xxx',
  debug: __DEV__,
  onUpdate: (update) => console.log(update),
  appId: 'your-app-id',
  serverUrl: 'https://api.swiftpatch.io/v1',
  checkOnResume: true,
  checkInterval: 0,
  installMode: InstallMode.ON_NEXT_RESUME,
  mandatoryInstallMode: InstallMode.IMMEDIATE,
  publicKey: '-----BEGIN PUBLIC KEY-----\n...',
  customHeaders: { 'X-Custom': 'value' },
  crashDetectionWindowMs: 10000,
  maxCrashesBeforeRollback: 2,
  autoStabilizeAfterLaunches: 2,
  sdkPin: '1234',
});

Advanced Options Reference

Option	Type	Default	Description
appId	string	From native config	Stable App ID.
serverUrl	string	https://api.swiftpatch.io/v1	API URL. Change only for self-hosted installations.
checkOnResume	boolean	true	Check for updates on app resume.
checkInterval	number	0	Minimum milliseconds between checks. 0 = every time.
installMode	InstallMode	ON_NEXT_RESUME	When to apply non-mandatory updates.
mandatoryInstallMode	InstallMode	IMMEDIATE	When to apply mandatory updates.
publicKey	string	From native config	RSA (a widely used encryption algorithm that uses a pair of keys) public key for bundle signing verification.
customHeaders	Record<string, string>	{}	Custom HTTP headers for every API request.
crashDetectionWindowMs	number	10000	Crash detection time window in milliseconds.
maxCrashesBeforeRollback	number	2	Crashes within the window before auto-rollback.
autoStabilizeAfterLaunches	number	2	Successful launches before promoting to stable.
sdkPin	string	null	PIN to open the built-in debug dashboard modal.

---

Install Modes

import { InstallMode } from '@swiftpatch/react-native';

InstallMode.IMMEDIATE        // Restart immediately
InstallMode.ON_NEXT_RESTART  // Apply on next full restart
InstallMode.ON_NEXT_RESUME   // Apply on next resume from background (default)

Mode	Best for	User experience
IMMEDIATE	Critical security patches	Restarts instantly. Use sparingly.
ON_NEXT_RESTART	Large updates	Waits for the user to close and reopen.
ON_NEXT_RESUME	Most updates	Applies silently on background return.

---

Common Examples

Development Logging

export default withSwiftPatch(App, { debug: __DEV__ });

Custom Update Alert

export default withSwiftPatch(App, {
  onUpdate: (update) => {
    Alert.alert('Update Available', `Version ${update.label} is ready.`);
  },
});

Bundle Signing

export default withSwiftPatch(App, {
  publicKey: `-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----`,
});

warning

Configure your signing key in the dashboard before enabling client-side verification. See Bundle Signing.

In-App Debug Dashboard

export default withSwiftPatch(App, { sdkPin: '1234' });

Shake the device and enter the PIN to inspect the current bundle, check for updates, or trigger rollbacks.

Self-Hosted Server

export default withSwiftPatch(App, {
  serverUrl: 'https://swiftpatch.internal.yourcompany.com/api/v1',
});

Immediate Updates

import { InstallMode } from '@swiftpatch/react-native';

export default withSwiftPatch(App, {
  installMode: InstallMode.IMMEDIATE,
  mandatoryInstallMode: InstallMode.IMMEDIATE,
});

warning

Immediate restarts interrupt the user. Reserve this for critical fixes.

---

Native Config Keys

Key	Platform	Required	Description
SwiftPatchAppId	iOS / Android	Yes*	App ID from the dashboard. Recommended.
SwiftPatchAppToken	iOS / Android	Yes*	App token (at_...). Direct token auth.
SwiftPatchDeploymentKey	iOS / Android	Yes*	Deployment key (dk_...). Targets a specific channel.
SwiftPatchProjectId	iOS / Android	No	Project ID for multi-project setups.
SwiftPatchServerUrl	iOS / Android	No	Custom server URL.
SwiftPatchPublicKey	iOS / Android	No	RSA public key for bundle signing.

* Provide one of SwiftPatchAppId, SwiftPatchAppToken, or SwiftPatchDeploymentKey. Priority: deploymentKey > appToken > appId.

tip

Use SwiftPatchAppId for new projects. It's stable across channel changes and supports automatic token rotation.