@capa-build/live-updates-plugin

The official capa.build plugin for CapacitorJS. It enables secure, atomic, and telemetry-integrated Over-The-Air (OTA) updates for your mobile applications.

🚀 Features

• 🔋 iOS & Android Support: Native bundle management for Capacitor 6, 7, and 8.
• ⚡️ Atomic Updates: Bundles are fully downloaded and verified before activation to prevent partial updates.
• 🛡️ Rollback Mechanism: Automatically restores a known working version if a new bundle fails to initialize.
• 📡 Real-time Telemetry: Automatic reporting of version adoption and health metrics to the Capa console.
• 📦 Delta Updates: Optimized per-file downloads for faster and lighter updates.
• 🔒 Security: File integrity verification using SHA-256 hashes and optional signature verification.

📦 Installation

npm install @capa-build/live-updates-plugin
npx cap sync

⚙️ Configuration

Add the plugin configuration to your capacitor.config.json (or capacitor.config.ts):

{
  "plugins": {
    "CapaLiveUpdates": {
      "appId": "YOUR_APP_ID_FROM_CAPA_BUILD",
      "autoUpdateStrategy": "background",
      "readyTimeout": 10000,
    }
  }
}

Configuration Options

| Property | Type | Description | | :--- | :--- | :--- | | appId | string | Your application's unique ID in the capa.build platform. | | autoUpdateStrategy | string | Update strategy: none, background (at startup), foreground (when app returns from background). | | readyTimeout | number | Max time (ms) the plugin waits for the ready() call before triggering a rollback. Default: 10000. | | publicKey | string | (Optional) Public key for bundle signature verification. | | serverDomain | string | (Optional) The domain of the Capa API. Default: api.capa.build. |

📖 Usage

Initialization (Ready Protocol)

It is critical to call the ready() method once your application has successfully loaded (e.g., after your framework—Vue, React, Angular—is mounted). If ready() is not called within the readyTimeout, the plugin assumes the bundle is faulty and triggers an automatic rollback.

import { CapaLiveUpdates } from '@capa-build/live-updates-plugin';

// Inside your App's initialization lifecycle
onMounted(async () => {
  try {
    const result = await CapaLiveUpdates.ready();
    console.log('App ready. Current Bundle:', result.currentBundleId);
    
    if (result.rollback) {
      console.warn('A failure was detected and an automatic rollback was performed.');
    }
  } catch (e) {
    console.error('Error notifying ready:', e);
  }
});

Manual Synchronization

You can trigger an update check and download at any time:

const result = await CapaLiveUpdates.sync();
if (result.updateAvailable) {
  console.log('New version downloaded:', result.bundleId);
  // You can prompt the user to reload now or later
}

Advanced Synchronization (Check without Download)

If you want to check if an update exists before downloading it:

const result = await CapaLiveUpdates.fetchLatestBundle();
if (result.updateAvailable) {
  console.log('Update found:', result.versionName);
  
  // Later, download it manually
  await CapaLiveUpdates.downloadBundle({
    bundleId: result.bundleId!,
    url: result.url!,
    artifactType: result.artifactType
  });
}

Apply Changes (Reload)

To apply a newly downloaded bundle immediately without waiting for the next app restart:

await CapaLiveUpdates.reload();

🛠 API Reference

Methods

| Method | Parameters | Returns | Description | | :--- | :--- | :--- | :--- | | sync | options?: SyncOptions | Promise<SyncResult> | Checks, downloads and sets the latest bundle. | | fetchLatestBundle | options?: SyncOptions | Promise<FetchLatestBundleResult> | Checks for updates without downloading. | | downloadBundle | options: DownloadBundleOptions | Promise<void> | Manually downloads a specific bundle. | | setBundle | options: SetBundleOptions | Promise<void> | Assigns a bundle for the next reload. | | getBundles | - | Promise<GetBundlesResult> | Lists all downloaded bundle IDs. | | getDownloadedBundles| - | Promise<GetDownloadedBundlesResult> | Lists detail of downloaded bundles. | | getCurrentBundle | - | Promise<BundleInfo> | Returns info about the active bundle. | | getNextBundle | - | Promise<{ bundleId: string \| null }> | Returns info about the bundle for the next reload. | | getChannel | - | Promise<ChannelResult> | Gets current configured channel. | | setChannel | options: SetChannelOptions | Promise<void> | Sets active channel (e.g., 'production'). | | fetchChannels | - | Promise<FetchChannelsResult> | Lists available channels from server. | | ready | - | Promise<ReadyResult> | Notifies app is loaded correctly. | | reload | - | Promise<void> | Reloads the webview with the next bundle. | | reset | - | Promise<void> | Restores the original app version. | | setCustomId | options: { customId: string } | Promise<void> | Sets a custom user ID for segmentation. |

Interfaces

SyncResult

• updateAvailable: boolean
• bundleId: string | null

FetchLatestBundleResult

• updateAvailable: boolean
• bundleId: string | null
• url: string | null
• versionCode: string | null
• versionName: string | null
• artifactType: 'manifest' | 'zip'

BundleInfo

• bundleId: string | null
• versionName: string | null
• versionCode: string | null

📡 Events

The plugin emits events to provide feedback to your users:

// Download progress
CapaLiveUpdates.addListener('onDownloadProgress', (event) => {
  const progress = (event.bytesReceived / event.totalBytes) * 100;
  console.log(`Downloading update: ${progress.toFixed(0)}%`);
});

// Update applied (ready for reload)
CapaLiveUpdates.addListener('onUpdateApplied', (event) => {
  console.log('Bundle is ready in local storage.');
});

📊 Automatic Telemetry

The plugin automatically reports the following data to capa.build every time ready() is called:

• deviceId: An anonymous unique identifier for the device.
• bundleId: The ID of the currently running bundle.
• platform: ios or android.
• pluginVersion: The version of the plugin being used.

This enables real-time visualization of version adoption and health metrics in the Capa Dashboard.

⚖️ License

Proprietary of Continuous Labs. All rights reserved. For exclusive use by capa.build customers.