Core — Lifecycle

Five methods on NativeUpdatePlugin manage the lifecycle of the plugin itself. Every other method on every other feature area depends on initialize() having resolved.

import { NativeUpdate } from 'native-update';
import type { PluginInitConfig, UpdateConfig } from 'native-update';

Method	When you call it
initialize(config)	Once at app boot, before any other plugin call
isInitialized()	Defensive checks; tests; debug screens
configure(config)	Alternative first-time configuration shape; locked after initialization
reset()	Clear downloaded bundles and configuration, then allow reinitialization
cleanup()	Release resources before app shutdown / on logout

---

initialize(config)

initialize(config: PluginInitConfig): Promise<void>

The first call. Sets up storage, validates config, registers OS task identifiers (if background updates are enabled in the config), and resolves the promise once the plugin is ready.

Parameters — see Core — Config for every field on PluginInitConfig.

Throws INVALID_CONFIG (required field missing or out of range), STORAGE_ERROR (cannot access app sandbox).

Idempotency — subsequent calls are ignored while initialized, even when values differ. To change locked configuration, call reset() and then initialize() again.

import { NativeUpdate, UpdateStrategy, ChecksumAlgorithm } from 'native-update';

await NativeUpdate.initialize({
  appId: 'com.yourcompany.yourapp',
  serverUrl: 'https://updates.yourdomain.com',
  apiKey: import.meta.env.VITE_NATIVE_UPDATE_API_KEY,
  channel: 'production',
  publicKey: import.meta.env.VITE_NATIVE_UPDATE_PUBLIC_KEY,
  requireSignature: true,
  checksumAlgorithm: ChecksumAlgorithm.SHA256,
  updateStrategy: UpdateStrategy.BACKGROUND,
  autoCheck: true,
  checkInterval: 3_600_000,                  // ms — note: PluginInitConfig is in ms
  enableLogging: import.meta.env.DEV,
});

Where to call it

Call initialize() from your app entry file (src/main.ts, src/main.tsx, App.vue, etc.) before you mount the UI. Calling from a deeply-nested component leaks plugin state to whichever component happens to render first.

---

isInitialized()

isInitialized(): Promise<boolean>

Asynchronous check. Resolves true once initialize() has completed. Useful in defensive code and tests.

if (!(await NativeUpdate.isInitialized())) {
  console.warn('[native-update] plugin not initialised yet');
  return;
}
await NativeUpdate.sync();

configure(config)

configure(config: UpdateConfig | { config: PluginInitConfig }): Promise<void>

Configure and initialize the plugin using either accepted argument shape. This method is only valid before initialization; afterward it rejects with INVALID_CONFIG because update-server and trust settings are immutable for the session.

// Style A — pass a partial UpdateConfig directly:
await NativeUpdate.configure({ liveUpdate: { channel: 'beta' } });

// Style B — pass a full PluginInitConfig wrapped in { config: ... }:
await NativeUpdate.configure({ config: { ...everything, channel: 'beta' } });

Prefer initialize() for new code. setChannel() remains the supported runtime channel preference. To change server URL, API key, public key, allowed hosts, or signature policy, call reset() and initialize again. setUpdateUrl() is a deprecated no-op.

---

reset()

reset(): Promise<void>

Cancels active downloads, deletes downloaded OTA bundles and cached versions, removes listeners, restores default configuration, and marks the plugin uninitialized. The app returns to its binary-shipped web bundle. Call initialize() afterward before using update methods again.

// Roll back to the binary's original bundle:
await NativeUpdate.reset();

---

cleanup()

cleanup(): Promise<void>

Releases resources held by the plugin — closes file handles, cancels in-flight downloads, removes event listeners registered internally, deregisters the background task. Call:

• Before app shutdown (typically wired to a beforeunload handler on web; rarely needed on mobile).
• On user logout if you want to fully tear down the plugin between sessions.
• In test teardown.

afterEach(async () => {
  await NativeUpdate.cleanup();
});

cleanup() is destructive — after it resolves, isInitialized() returns false and you must initialize() again before using any other method.

---

Calling order

Practical rules:

• Never call any feature method before initialize() resolves — you get NOT_CONFIGURED.
• initialize() is idempotent; safe to call from multiple bootstrap paths.
• cleanup() requires re-initialize() before next use.

---

Plugin manager (power-user export)

For advanced scenarios (custom test harnesses, embedding the SDK in another framework's lifecycle), the plugin exports PluginManager directly:

import { PluginManager } from 'native-update';

PluginManager exposes the lower-level lifecycle hooks the friendly facade above wraps. Most apps never need it — it is documented for completeness, not because typical apps should reach for it.

---

Lifecycle reference verified against src/definitions.ts in the plugin repo as of 2026-05-11. Documented by Ahsan Mahmood.