Exploring the Capacitor Live Update API¶

Modern mobile application development requires agility and the ability to deliver updates quickly to users without the lengthy app store review process. The Capacitor Live Update plugin from Capawesome revolutionizes how developers deploy updates to their Ionic and Capacitor applications, enabling Over-the-Air (OTA) updates that allow instant delivery of new features, bug fixes, and content changes directly to users' devices without requiring them to download a new version from app stores.

Prerequisites¶

Before diving into the Capacitor Live Update API, ensure you have a Capawesome Cloud 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 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(...) method. This method checks for available updates and downloads them if necessary:

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(...) method:

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(...) method:

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:

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(...) method:

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(...) method. This is useful if you first want to check for updates using the fetchLatestBundle(...) method and then decide when to download them:

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(...) method. This way, the bundle will be used the next time the app is restarted:

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(...) method:

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 event listener:

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(...) method:

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(...) method:

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:

{
  "plugins": {
    "LiveUpdate": {
      "autoDeleteBundles": true
    }
  }
}

Best Practices¶

When implementing live updates with the Capacitor Live Update API, consider these best practices:

Enable Automatic Rollback: Set the readyTimeout option to automatically roll back to the previous bundle 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.
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.
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.

Conclusion¶

The Capacitor Live Update Plugin from Capawesome provides a powerful solution for delivering instant updates to Ionic applications without the constraints of traditional app store distribution. By enabling Over-the-Air updates, developers can respond quickly to user feedback, fix critical issues, and deploy new features with unprecedented agility.

To stay updated with the latest updates, features, and news about the Capawesome, Capacitor, and Ionic ecosystem, subscribe to the Capawesome newsletter and follow us on X (formerly Twitter).

If you have any questions or need assistance with the Capacitor Live Update Plugin, feel free to reach out to the Capawesome team. We're here to help you implement seamless OTA updates in your Ionic applications.