Live Update — Config
LiveUpdateConfig is the configuration block passed to NativeUpdate.initialize() (under liveUpdate, or as part of the top-level PluginInitConfig shorthand). Every field except appId is optional, but a few — serverUrl, publicKey, requireSignature — are effectively required for a production setup.
import type { LiveUpdateConfig } from 'native-update';
Full type
interface LiveUpdateConfig {
appId: string;
serverUrl?: string;
apiKey?: string; // since v3.1.3
channel?: string;
autoUpdate?: boolean;
updateStrategy?: UpdateStrategy;
publicKey?: string;
requireSignature?: boolean;
checksumAlgorithm?: ChecksumAlgorithm;
checkInterval?: number;
allowEmulator?: boolean;
mandatoryInstallMode?: InstallMode;
optionalInstallMode?: InstallMode;
maxBundleSize?: number;
maxUncompressedBundleSize?: number;
allowedHosts?: string[];
allowUnsignedDevelopmentUpdates?: boolean;
enableDeltaUpdates?: boolean;
}
Field reference
appId
| Type | string |
| Required | yes |
| Default | — |
The Capacitor app ID (matches capacitor.config.ts → appId). The server uses this to scope which bundles a device is allowed to download.
appId: 'com.yourcompany.yourapp'
serverUrl
| Type | string |
| Required | yes when using Live Update |
| Default | — |
HTTPS origin of your update server. Plain HTTP is rejected at startup — use HTTPS even in development. Trailing slash is optional. The plugin appends /v1/updates/check itself, so for the hosted backend the value is:
serverUrl: 'https://nativeupdatebe.aoneahsan.com/api'
apiKey
| Type | string |
| Required | yes for the hosted backend (every check without it is skipped / rejected) |
| Since | v3.1.3 (earlier versions only accepted it via the flat initialize({ apiKey })) |
| Default | — |
The app API key, sent as the X-API-Key header on every update check (web AND native since v3.1.3). Mint, copy, rotate, or delete keys in the dashboard: Apps → your app → API Keys (max 3 active keys per app; lifecycle actions are rate-limited).
apiKey: 'nu_app_…'
channel
| Type | string |
| Required | no |
| Default | 'production' (server-side convention; SDK does not enforce a list) |
The release channel the device tracks. Common values: production, staging, beta, dev. Channel switching at runtime is supported via setChannel().
autoUpdate
| Type | boolean |
| Required | no |
| Default | false |
When true, sync() automatically downloads available updates. When false, sync() returns UPDATE_AVAILABLE and you call downloadUpdate() yourself. Most apps want false so the user sees a prompt before bytes start moving on metered connections.
updateStrategy
| Type | UpdateStrategy |
| Required | no |
| Default | 'background' |
How a READY bundle is applied. See the enum for tradeoffs. Override per-call via SyncOptions.updateMode.
publicKey
| Type | string (PEM-encoded) |
| Required | when requireSignature: true |
| Default | — |
PEM-encoded RSA public key. Generated by npx native-update keys generate (2048 or 4096 bits). Keep the public half here in your app config; the private half stays on your CI / signing server and never ships in the binary.
requireSignature
| Type | boolean |
| Required | no |
| Default | true |
Every downloaded bundle must carry an RSA-SHA256 signature that verifies against publicKey. Disabling this requires the explicit allowUnsignedDevelopmentUpdates: true escape hatch, and native release builds ignore that escape hatch and continue requiring signatures.
checksumAlgorithm
| Type | ChecksumAlgorithm |
| Required | no |
| Default | 'SHA-256' |
Algorithm used for bundle integrity checks. Must match the algorithm used by your CLI signing step.
checkInterval
| Type | number (seconds) |
| Required | no |
| Default | 0 (no auto-check) |
Interval between automatic background sync calls, in seconds. 0 disables periodic checks (you call sync() manually). Common values: 3600 (hourly), 21600 (every 6 hours).
allowEmulator
| Type | boolean |
| Required | no |
| Default | false |
When false, sync calls fail on emulators / simulators with PLATFORM_NOT_SUPPORTED. Set to true for QA / CI flows running in emulators. Always false in production builds.
mandatoryInstallMode
| Type | InstallMode |
| Required | no |
| Default | 'immediate' |
How updates flagged mandatory: true by the server are applied. Default forces an immediate reload — the user cannot defer a mandatory update.
optionalInstallMode
| Type | InstallMode |
| Required | no |
| Default | 'on_next_restart' |
How updates not flagged mandatory are applied. Default waits until the next restart so the user is not interrupted.
maxBundleSize
| Type | number (bytes) |
| Required | no |
| Default | 100 MB |
Hard downloaded-size cap. Bundles exceeding this are rejected before install.
maxUncompressedBundleSize
| Type | number (bytes) |
| Required | no |
| Default | 500 MB |
Caps the total extracted size of a ZIP bundle. This is independent of maxBundleSize and protects native
installers from highly compressed zip bombs.
enableDeltaUpdates
| Type | boolean |
| Required | no |
| Default | true |
Uses verified NUDELTA/1 patches when the backend advertises one for the current bundle. Every mismatch or
patch failure falls back to the signed full ZIP automatically.
allowUnsignedDevelopmentUpdates
| Type | boolean |
| Required | only when setting requireSignature: false |
| Default | false |
Explicit development-only escape hatch. Native release builds ignore it. Never enable this in a production configuration.
allowedHosts
| Type | string[] |
| Required | no |
| Default | [] (every HTTPS host accepted) |
Allow-list of hostnames for bundle and patch downloads. When non-empty, any URL whose host is not in the list is rejected with INSECURE_URL. setUpdateUrl() is a deprecated no-op; call reset() and initialize again to change locked configuration.
allowedHosts: ['updates.yourdomain.com', 'cdn.yourdomain.com']
Recommended production config
const liveUpdate: LiveUpdateConfig = {
appId: 'com.yourcompany.yourapp',
serverUrl: 'https://updates.yourdomain.com',
channel: 'production',
autoUpdate: false,
updateStrategy: UpdateStrategy.BACKGROUND,
publicKey: import.meta.env.VITE_NATIVE_UPDATE_PUBLIC_KEY,
requireSignature: true,
checksumAlgorithm: ChecksumAlgorithm.SHA256,
checkInterval: 3600, // hourly auto-check
allowEmulator: false,
mandatoryInstallMode: InstallMode.IMMEDIATE,
optionalInstallMode: InstallMode.ON_NEXT_RESTART,
maxBundleSize: 100 * 1024 * 1024,
maxUncompressedBundleSize: 500 * 1024 * 1024,
enableDeltaUpdates: true,
allowedHosts: ['updates.yourdomain.com'],
};
Recommended development config
const liveUpdate: LiveUpdateConfig = {
appId: 'com.yourcompany.yourapp',
serverUrl: 'https://dev-updates.yourdomain.com',
channel: 'dev',
autoUpdate: true,
updateStrategy: UpdateStrategy.IMMEDIATE,
requireSignature: false,
allowUnsignedDevelopmentUpdates: true,
allowEmulator: true,
checkInterval: 60, // every minute for fast iteration
};
Unsigned mode is for explicit debug workflows only and is ignored by native release builds. Live Update URLs still require HTTPS in development; use a trusted local TLS endpoint or tunnel.