Rollouts¶
Rollouts allow you to gradually release app updates by first rolling them out to a small percentage of users and then increasing the rollout to more users over time. This approach helps mitigate risks associated with new releases by limiting exposure to potential issues.
Manage Rollouts¶
You can manage rollouts associated with your app using the Capawesome CLI or the Capawesome Cloud Console.
Start a Rollout¶
Rollouts can be started when deploying a build to a live update channel.
To start a rollout using the Capawesome CLI, use the apps:liveupdates:upload command with the --rollout-percentage flag:
You will be prompted to select the app you want to upload the bundle for and to provide the path to the bundle file. The CLI will then upload and deploy the bundle to the specified channel in the Capawesome Cloud, starting a rollout to the specified percentage of users.
To start a rollout using the Capawesome Cloud Console, navigate to the app you want to start the rollout for, and click on the Deployments menu item in the sidebar. Next, click on the "Create Deployment" button, select the build to deploy, choose the live update channel, click on "Advanced", and set the "Rollout Percentage" to the desired initial percentage of users to receive the update.
Click on the "Create" button to complete the deployment and start the rollout.
Update Rollout Percentage¶
Update the rollout percentage to increase or decrease the number of users receiving the update.
To update the rollout percentage using the Capawesome CLI, use the apps:liveupdates:rollout command:
You will be prompted to select the app you want to update the rollout for and to provide the channel name and the new rollout percentage. The CLI will then update the rollout percentage for the latest deployment in this channel in the Capawesome Cloud.
To update the rollout percentage using the Capawesome Cloud Console, navigate to the app you want to update the rollout for, and click on the Deployments menu item in the sidebar. Next, click on the deployment you want to update the rollout for, click on the "Settings" tab, and update the rollout percentage to the desired percentage of users to receive the update.
Click on the "Save" button to complete the update of the rollout percentage.
Complete a Rollout¶
Complete a rollout to make the update available to all users.
To complete a rollout using the Capawesome CLI, use the apps:liveupdates:rollout command with a percentage of 100:
You will be prompted to select the app you want to complete the rollout for and to provide the channel name. The CLI will then complete the rollout for the latest deployment in this channel in the Capawesome Cloud.
To complete a rollout using the Capawesome Cloud Console, navigate to the app you want to complete the rollout for, and click on the Deployments menu item in the sidebar. Next, click on the deployment you want to complete the rollout for, click on the "Settings" tab, and set the rollout percentage to 100 to make the update available to all users.
Click on the "Save" button to complete the rollout.
Advanced¶
Multi-Channel Rollouts¶
You can implement multi-channel rollouts by using separate channels for the rollout and stable releases. For example, you can first check for an update in a "production-rollout" channel and, if no update is available, check in the "production" channel for the stable release. This way, users in the rollout phase receive updates from the "production-rollout" channel, while all other users receive updates from the stable "production" channel. The deployment in the "production-rollout" channel can be gradually increased until it reaches 100%, at which point you can deploy the same bundle to the "production" channel for all users. The rollout percentage in the "production" channel should always be set to 100% to ensure all other users receive the stable update.
Disable Automatic Updates
If you are manually handling the update process, it is strongly recommended to set the autoUpdateStrategy configuration option to none to prevent conflicts with the automatic update mechanism.
The following example demonstrates how to implement this logic using the Live Update plugin:
import { LiveUpdate } from '@capawesome/capacitor-live-update';
const sync = async () => {
// First, check for a rollout update in the "production-rollout" channel
const firstResult = await LiveUpdate.sync({ channel: `production-rollout` });
if (firstResult.nextBundleId) {
console.log(`App will be updated to rollout bundle ${firstResult.nextBundleId} on next restart`);
return;
}
// If no rollout update is available, check for the stable update in the "production" channel
const secondResult = await LiveUpdate.sync({ channel: `production` });
if (secondResult.nextBundleId) {
console.log(`App will be updated to stable bundle ${secondResult.nextBundleId} on next restart`);
} else {
console.log('App is up to date');
}
};
If a device is part of the rollout, it will always receive the update from the "production-rollout" channel first until a new deployment is made to that channel. This ensures that devices do not get stuck in an update loop. Once the rollout is complete, you can deploy the same bundle to the "production" channel for all users. The Live Update plugin will recognize that the device is already on the latest bundle and will not attempt to re-download it. You can then remove the "production-rollout" channel or keep it for the next rollout.
Limitations¶
Rollout Percentage Calculation¶
Rollout percentages are calculated based on the total number of devices in a channel, not just those compatible with the deployed bundle. When using Versioned Bundles, this means the actual rollout may reach fewer devices than the specified percentage if some devices are incompatible with the update. To ensure more accurate rollouts, use Versioned Channels so that only compatible devices are included in the rollout calculation.