--- title: Exploring the Capacitor Live Update API description: A complete tour of the Capacitor Live Update plugin API — every method, event, and config option, with code samples for each. date: created: 2025-07-08 updated: 2026-07-17 authors: - robingenz categories: - Capacitor - Guides - SDKs links: - Capacitor Live Update: sdks/capacitor/live-update.md faq: true --- # Exploring the Capacitor Live Update API This post is a tour of the [Capacitor Live Update plugin](../../sdks/capacitor/live-update.md) API. We'll walk through every method, event, and configuration option the plugin exposes — what each one does, when to reach for it, and a working code snippet you can copy. The goal is breadth: by the end, you should have a clear map of the entire API surface and know exactly which call to make for any given situation. If you're new to live updates and want strategy, setup, and a real-world end-to-end example first, start with [Capacitor Live Updates: A Complete Guide to OTA Updates](./capacitor-live-updates-guide.md) and come back here when you want the API reference. ## Video Tutorial This step-by-step walkthrough complements the API reference by showing a full Live Updates setup, first deployment, and practical runtime behavior in a real Capacitor app workflow.
## Prerequisites Before diving into the Capacitor Live Update API, ensure you have a [Capawesome Cloud](/){:target="_blank"} account. This is essential for managing your live updates and deploying them seamlessly to your applications. ## Installation To install the Capacitor Live Update plugin, please refer to the [Installation](../../sdks/capacitor/live-update.md/#installation) section in the plugin documentation. ## Usage Let's explore the core functionality of the Capacitor Live Update API and how to implement seamless OTA updates in your Ionic applications. ### Syncing Updates The primary method for delivering updates to your application is through the [`sync(...)`](../../sdks/capacitor/live-update.md#sync) method. This method checks for available updates and downloads them if necessary: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const syncUpdate = async () => { const result = await LiveUpdate.sync({ channel: 'production-5' }); if (result.nextBundleId) { console.log('New bundle downloaded:', result.nextBundleId); // Restart the app to apply the update await LiveUpdate.reload(); } else { console.log('No updates available'); } }; ``` The `sync(...)` method is designed to be non-blocking and will only download updates when they are available. It returns information about the next bundle ID that will be applied, allowing you to control when and how updates are implemented in your application. If you just want to check for updates without downloading them, you can use the [`fetchLatestBundle(...)`](../../sdks/capacitor/live-update.md#fetchlatestbundle) method: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const checkForUpdates = async () => { const result = await LiveUpdate.fetchLatestBundle({ channel: 'production-5' }); if (result.nextBundleId) { console.log('Latest bundle available:', result.nextBundleId); } else { console.log('No updates available'); } }; ``` ### Managing Update Channels Update channels provide a powerful way to manage different versions of your application for different audiences. You can set the current channel using the [`setChannel(...)`](../../sdks/capacitor/live-update.md#setchannel) method: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const setChannel = async () => { await LiveUpdate.setChannel({ channel: 'production-5'. // Specify the channel name }); }; ``` This allows you to deliver different versions of your app to different user groups, such as beta testers receiving experimental features while production users get stable releases. Alternatively, you can pass the channel name as an option to the `sync(...)` or `fetchLatestBundle(...)` methods: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const syncWithChannel = async (channelName: string) => { const result = await LiveUpdate.sync({ channel: channelName }); // Handle the result as needed }; ``` ### Retrieving Bundle Information To understand what bundles are available and currently active, use the [`getBundle(...)`](../../sdks/capacitor/live-update.md#getbundle) method: ```ts const getCurrentBundle = async () => { const { bundleId } = await LiveUpdate.getCurrentBundle(); console.log('Current bundle ID:', bundleId); return bundleId; }; ``` This method provides detailed information about the currently active bundle, including its ID, version, and status, helping you track which version of your app is running. ### Downloading Updates For more control over the update process, you can manually download updates using the [`downloadBundle(...)`](../../sdks/capacitor/live-update.md#downloadbundle) method. This is useful if you first want to check for updates using the `fetchLatestBundle(...)` method and then decide when to download them: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const downloadBundle = async (bundleId: string) => { await LiveUpdate.downloadBundle({ bundleId: bundleId }); }; ``` ### Setting Active Bundles Once a bundle is downloaded, you can set it as the next bundle using the [`setNextBundle(...)`](../../sdks/capacitor/live-update.md#setnextbundle) method. This way, the bundle will be used the next time the app is restarted: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const setNextBundle = async (bundleId: string) => { await LiveUpdate.setNextBundle({ bundleId: bundleId }); }; ``` If you want to apply the downloaded bundle immediately, you can use the [`reload(...)`](../../sdks/capacitor/live-update.md#reload) method: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const applyUpdate = async () => { await LiveUpdate.reload(); }; ``` ### Monitoring Download Progress For large updates, you can monitor download progress using the [`downloadProgress`](../../sdks/capacitor/live-update.md#addlistenerdownloadprogress) event listener: ```ts import { LiveUpdate } from '@capawesome/capacitor-live-update'; const addDownloadProgressListener = () => { LiveUpdate.addListener('downloadProgress', (event) => { console.log(`Download progress: ${event.progress * 100}%`); }); }; ``` This enables you to provide real-time feedback to users about update downloads, enhancing the user experience during the update process. ### Managing Local Bundles You can retrieve a list of all locally stored bundles using the [`getBundles(...)`](../../sdks/capacitor/live-update.md#getbundles) method: ```ts const listLocalBundles = async () => { const bundles = await LiveUpdate.getBundles(); bundles.forEach(bundle => { console.log(`Bundle ID: ${bundle.bundleId}, Status: ${bundle.status}`); }); return bundles; }; ``` To clean up storage space, you can delete unused bundles with the [`deleteBundle(...)`](../../sdks/capacitor/live-update.md#deletebundle) method: ```ts const cleanupOldBundles = async (bundleId: string) => { await LiveUpdate.deleteBundle({ bundleId: bundleId }); console.log(`Bundle ${bundleId} deleted`); }; ``` There is also a configuration option called `autoDeleteBundles` to automatically delete old bundles when a new one is applied. Just set it to `true` in your Capacitor configuration file: ```json { "plugins": { "LiveUpdate": { "autoDeleteBundles": true } } } ``` ## Best Practices When implementing live updates with the Capacitor Live Update API, consider these best practices: 1. **Enable Automatic Rollback**: Set the `readyTimeout` option to automatically roll back to the built-in bundle that shipped with the installed native app version if the new one fails to load within a specified time. This ensures a smooth user experience even if an update has issues. Make sure to call the `ready()` method directly at app startup to notify the plugin that no rollback is needed. 2. **Fetch Updates Efficiently**: Do not call the `sync(...)` or `fetchLatestBundle(...)` methods too frequently. Instead, implement a strategy to check for updates periodically or based on user actions, such as app startup or specific user interactions. The very best way is to notify devices about new updates via silent push notifications. 3. **Ask for User Consent**: Before applying updates, consider prompting users to confirm the update, especially for significant changes. This can help manage user expectations and ensure they are aware of the changes being made. ## FAQ ### What's the difference between `sync()` and `fetchLatestBundle()`? `sync()` checks for an update and downloads it if one exists, in a single call. `fetchLatestBundle()` only checks and reports whether a newer bundle is available, without downloading anything — useful when you want to know an update exists before committing to the download, for example to show a "new version available" indicator before the user opts to fetch it via `downloadBundle()`. ### Do I need to call `setChannel()` before every `sync()` call? No — you can pass the channel directly as an option to `sync()` or `fetchLatestBundle()` instead of calling `setChannel()` separately beforehand. Passing it inline keeps the channel selection explicit at each call site, which matters if you're switching channels based on runtime logic like the device's native version code. ### What happens to old bundles taking up storage on the device? By default, they stay on disk until you remove them — either individually with `deleteBundle()`, or automatically by setting `autoDeleteBundles: true` in your Capacitor config, which cleans up old bundles whenever a new one is applied. Use `getBundles()` first if you want to inspect what's stored before deciding whether to delete anything. ### Should I call `sync()` on a timer to keep checking for updates? No — this guide's own best practices explicitly warn against calling `sync()` or `fetchLatestBundle()` too frequently. Check on app startup or specific user interactions instead, and for anything that needs to happen faster than that, use a silent push notification to trigger the check on demand rather than polling. ### If I call `reload()` right after `downloadBundle()`, does the update apply immediately? Yes, but only if you've also set the downloaded bundle as the next bundle first (via `setNextBundle()`, or automatically as part of `sync()`). `reload()` applies whatever bundle is currently marked as "next" — it doesn't implicitly promote a bundle you've only downloaded, so skipping `setNextBundle()` between `downloadBundle()` and `reload()` will just reload the app on its current bundle. ## Next steps For deeper rollout and channel management strategies, see [Managing Channels and Rollouts for Live Updates](https://www.youtube.com/watch?v=Hg0ObWno3Zc){:target="_blank"}. For bundle integrity and security, see [Secure Your Live Updates with Code Signing](https://www.youtube.com/watch?v=Z-Qu2f-ODv8){:target="_blank"}. [Try Capawesome Cloud Free](https://capawesome.io){ .md-button .md-button--primary } ## Conclusion That's the full surface of the Capacitor Live Update API — `sync()` and `fetchLatestBundle()` to check for new bundles, `downloadBundle()` and `setNextBundle()` for fine-grained control, `reload()` to apply, `ready()` to signal a successful start, plus the listeners and bundle-management helpers around them. Most apps only need `sync()`, `ready()`, and a `nextBundleSet` listener; the rest of the API is there for the cases where you need it. For the bigger picture — update strategies, versioning, code signing, best practices, and a complete real-world example — see [Capacitor Live Updates: A Complete Guide to OTA Updates](./capacitor-live-updates-guide.md). If you have questions or want to share how you're using the plugin, join us in the [Capawesome Discord server](https://discord.gg/VCXxSVjefW){:target="_blank"} or subscribe to the [Capawesome newsletter](https://capawesome.io/newsletter/){:target="_blank"} for new posts in your inbox.