Capacitor Plugin API Reference

Complete API reference for @deploy-your-app/capacitor-update-manager. For the concepts behind these calls, see Update lifecycle.

import { DeployYourApp, DYA_EVENTS } from '@deploy-your-app/capacitor-update-manager';

Update methods

checkForUpdate(options?)

Asks the update server whether a newer bundle exists for this device. Emits updateAvailable or noUpdateAvailable. Before the network call, any pending bundle whose delayUntil has passed is staged for the next launch.

const result = await DeployYourApp.checkForUpdate();
const beta = await DeployYourApp.checkForUpdate({ channel: 'beta' });

Returns Promise<UpdateCheckResult>.

download(options)

Downloads a bundle ZIP, verifies its SHA-256 checksum, verifies the RSA signature when publicKey is configured and a signature was supplied, decrypts it when a sessionKey is supplied, and extracts it to device storage. Emits downloadProgress while running, then downloadComplete or downloadFailed.

const bundle = await DeployYourApp.download({
  url: result.url,
  version: result.version,
  checksum: result.checksum,
  signature: result.signature,
  sessionKey: result.sessionKey,
});

Returns Promise<DownloadResult>.

Rejects with DOWNLOAD_FAILED when another download is already running, or when version equals the currently served bundle. Rejects with EXTRACTION_FAILED when the archive contains no index.html at its root or in a single top-level folder.

apply(options)

Activates a downloaded bundle immediately: the webview is pointed at the new bundle and reloaded. Starts the app-ready timer, so the new bundle must call notifyAppReady() within appReadyTimeout or the plugin rolls back. Emits updateApplied or updateFailed.

await DeployYourApp.apply({ id: bundle.id });

Returns Promise<void>. Rejects with BUNDLE_NOT_FOUND when the bundle is not on disk.

notifyAppReady()

Confirms the current bundle booted. Cancels the rollback timer, marks the bundle active, clears the launch-attempt counter, and deletes the previous bundle when autoDeletePrevious is enabled. Emits appReady.

await DeployYourApp.notifyAppReady();

Returns Promise<void>. Safe to call on every launch.

reset()

Deletes every downloaded bundle and its metadata, then serves the built-in bundle shipped in the app binary.

await DeployYourApp.reset();

Returns Promise<void>.

reload()

Reloads the webview without changing which bundle is served.

await DeployYourApp.reload();

Returns Promise<void>.

Bundle methods

getCurrentBundle()

Metadata for the bundle being served. Returns { id: 'builtin', version: '0.0.0', status: 'builtin' } when the built-in bundle is active.

const bundle = await DeployYourApp.getCurrentBundle();

Returns Promise<BundleInfo>.

getNextBundle()

The bundle staged to activate on the next launch, or null when nothing is staged.

const next = await DeployYourApp.getNextBundle();

Returns Promise<BundleInfo | null>.

listBundles()

Every downloaded bundle still on the device. The built-in bundle is not included.

const { bundles } = await DeployYourApp.listBundles();

Returns Promise<{ bundles: BundleInfo[] }>.

deleteBundle(options)

Removes a bundle's files and metadata. Deleting the bundle currently being served reverts the webview to the built-in bundle.

await DeployYourApp.deleteBundle({ id: '1.2.3' });

Returns Promise<void>.

Channel and device methods

getChannel()

const { channel } = await DeployYourApp.getChannel();

Returns Promise<{ channel: string }>.

setChannel(options)

Switches the update channel and persists it to device storage, so it survives restarts and overrides the channel value in the Capacitor config. Used by the next update check.

await DeployYourApp.setChannel({ channel: 'beta' });

Returns Promise<void>.

getDeviceId()

The device UUID the plugin generated on first use and stored locally. It is not derived from any hardware or advertising identifier.

const { deviceId } = await DeployYourApp.getDeviceId();

Returns Promise<{ deviceId: string }>.

setCustomId(options)

Stores a custom identifier for this device. It is included in the update-check request body.

await DeployYourApp.setCustomId({ customId: 'employee-4521' });

Returns Promise<void>. The current DeployYourApp server validates the update-check body against a schema that does not include customId, so the value is discarded rather than stored.

Version methods

getNativeVersion()

The native app version — CFBundleShortVersionString on iOS, versionName on Android.

const { version } = await DeployYourApp.getNativeVersion();

Returns Promise<{ version: string }>.

getPluginVersion()

const { version } = await DeployYourApp.getPluginVersion();

Returns Promise<{ version: string }>.

setVersionOverride(options)

Reports a different bundle version to the update server on subsequent checks, without touching the bundle on disk. Persisted across restarts.

await DeployYourApp.setVersionOverride({ version: '0.0.1' });
await DeployYourApp.setVersionOverride({ version: '' }); // clear

Returns Promise<void>.

getVersionOverride()

const { version } = await DeployYourApp.getVersionOverride();

Returns Promise<{ version: string }> — an empty string when no override is set.

Analytics methods

Events are buffered on device and posted to {statsUrl}/api/stats. A flush happens when analyticsBatchSize events are buffered or every analyticsFlushInterval seconds, whichever comes first. The buffer holds at most 500 events; the oldest are dropped first. A failed batch is retried three times with 1s / 2s / 4s backoff, then pushed back into the buffer for the next cycle. A 4xx response is not retried.

Nothing is sent when analyticsEnabled is false.

trackEvent(options)

await DeployYourApp.trackEvent({
  name: 'checkout_completed',
  properties: { plan: 'scale', total: 29 },
});

Returns Promise<void>.

trackPageView(options)

Records an event with eventType: 'page_view'.

await DeployYourApp.trackPageView({ path: '/settings', title: 'Settings' });

Returns Promise<void>.

trackError(options)

Records an event with eventType: 'error'.

await DeployYourApp.trackError({ message: err.message, stack: err.stack, fatal: false });

Returns Promise<void>.

flushAnalytics()

Sends the buffered events now. Resolves even when the send fails — failed events stay buffered for the next cycle.

await DeployYourApp.flushAnalytics();

Returns Promise<void>.

Events the plugin records itself

With analytics enabled, the plugin writes its own update lifecycle events into the same buffer. They are stored as structured device update events on the server.

Events

Listen with the standard Capacitor listener API. Name constants are exported as DYA_EVENTS.

const handle = await DeployYourApp.addListener(DYA_EVENTS.DOWNLOAD_PROGRESS, (progress) => {
  console.log(`Download: ${progress.percent}%`);
});

await handle.remove();

Several of these fire during launch, before your web code can register a listener. Those are retained by Capacitor and delivered to the first listener that attaches: updateAvailable, downloadComplete, downloadFailed, updateApplied, updateFailed, rollback, and appVersionChange. The remaining events — downloadProgress, noUpdateAvailable, appReady, and testGestureTrigger — are not retained.

removeAllListeners() removes every listener registered through the plugin.

Types

BundleInfo

pending means served or staged but not yet confirmed by notifyAppReady(). active means confirmed. failed means rolled back.

UpdateCheckResult

Every property except available and mandatory is absent when no update is available.

DownloadResult

DownloadProgressEvent

Error codes

Rejected calls carry a stable code property alongside message.

try {
  await DeployYourApp.download(update);
} catch (err) {
  if (err.code === 'CHECKSUM_MISMATCH') {
    // corrupted download — retry
  }
}

Two codes are not raised identically on both platforms. INVALID_URL is raised on iOS only; on Android a malformed URL surfaces as UNKNOWN. PARSE_ERROR covers malformed update-check JSON on iOS; on Android that case also surfaces as UNKNOWN. Branch on UNKNOWN as a catch-all rather than assuming a code is platform-symmetric.

Server contract

The plugin talks to exactly two endpoints. Everything else in the DeployYourApp API is dashboard-facing and requires authentication.

POST {updateUrl}/api/update

Rate limited to 60 requests per minute. Request body:

{
  "appId": "com.yourcompany.yourapp",
  "platform": "ios",
  "channel": "production",
  "deviceId": "0f4b1c1e-8a2f-4c3a-9b1e-2f5d6a7b8c90",
  "customId": "",
  "nativeVersion": "1.4.0",
  "nativeBuild": "142",
  "currentVersion": "1.3.2",
  "currentBundleId": "1.3.2",
  "pluginVersion": "0.1.0"
}

platform is ios or android. Android additionally sends osVersion and device. The server's schema covers appId, deviceId, platform, currentVersion, nativeVersion, pluginVersion, and channel; the remaining fields are accepted but discarded.

A 204 No Content response means no update, and the plugin treats it as { available: false }. The server answers 204 for an unknown app, a missing or empty channel, a device not subscribed to a private channel, a bundle for another platform, a version the device already runs, a blocked major/minor step or downgrade, a native version outside the bundle's compatibility range, a scheduled deployment that has not started, and a device outside the rollout percentage.

A 200 response carries the JSON that becomes UpdateCheckResult. Any other status rejects with NETWORK_ERROR.

POST {statsUrl}/api/stats

Rate limited to 100 requests per minute. Batches carry at most 100 events.

{
  "appId": "com.yourcompany.yourapp",
  "deviceId": "0f4b1c1e-8a2f-4c3a-9b1e-2f5d6a7b8c90",
  "events": [
    {
      "eventType": "page_view",
      "eventData": { "path": "/settings", "title": "Settings" },
      "bundleVersion": "1.3.2",
      "timestamp": "2026-07-31T12:00:00.000Z"
    }
  ]
}

bundleVersion is filled in by the plugin with the active bundle's version, or builtin.

Web platform

The plugin registers a web implementation so imports resolve in a browser or PWA build, but a browser cannot swap the served assets. Behaviour differs:

No plugin events are emitted on web.