Managing App Versioning and Updates

1. Configuring App Version

Property	Value	Description
version	`"1.0.0"`	Current app version string
build	`"1"`	Build number for internal tracking

Example: Setting version in config

{
  "name": "MyApp",
  "version": "1.0.0",
  "build": "1"
}

Note: Version should follow semantic versioning (SemVer) format.

2. Managing Build Numbers

Property	Value	Description
buildNumber	`1`	Incremental number for each build, used by app stores to identify versions
version	`1.0.0`	Version string following semantic versioning (e.g., 1.0.0, 2.1.3)

Example: Setting buildNumber in config

<widget id="com.example.app" version="1.0.0">
  <platform name="android">
    <config-file target="AndroidManifest.xml" parent="/manifest">
      <uses-permission android:name="android.permission.INTERNET" />
    </config-file>
    <resource-file src="resources/android/icon.png" target="icon.png" />
  </platform>
  <engine name="android" spec="^10.1.1" />
</widget>

Note: For Android, the buildNumber is typically managed in build.gradle under android { defaultConfig { versionCode }}.

Example: Setting buildNumber in Gradle

android {
  compileSdkVersion 33
  defaultConfig {
    applicationId "com.example.app"
    minSdkVersion 21
    targetSdkVersion 33
    versionCode 20230405
    versionName "1.0.0"
  }
}

3. Implementing In-App Updates

Property	Description	Values	Notes
updateMethod	Defines how the app update is handled	`auto`, `manual`	Default is `auto`
updateUrl	URL to fetch update manifest or binary	`string`	Required for manual updates
versionCheckInterval	How often to check for updates (in ms)	`number`	Defaults to 300000 (5 minutes)

Example: Configure In-App Updates

import { Plugins } from '@capacitor/core';

const { AppUpdater } = Plugins;

AppUpdater.configure({
  updateMethod: 'auto',
  updateUrl: 'https://example.com/app-update.json',
  versionCheckInterval: 300000
});

Example: Manual Update Check

AppUpdater.checkForUpdate().then(result => {
  if (result.updateAvailable) {
    AppUpdater.downloadAndInstall();
  }
});

Note: Ensure your app has proper permissions to download and install updates on both iOS and Android.

Warning: Auto-updates can cause app store rejections if not handled properly. Always test update flows in a staging environment.

4. Using Live Updates

Ionic's Live Updates feature allows you to push code, asset, and configuration changes to your app without requiring users to download a new version from the app store.

Property	Description	Default
appId	The unique identifier for your app in the Ionic Pro dashboard.	None
channelId	The channel to pull updates from (e.g., 'production', 'staging').	None
serverUrl	The URL of the Ionic Pro server to fetch updates from.	`https://api.ionicjs.com`

Example: Configuring Live Updates

import { defineConfig } from &#x27;@ionic/cli&#x27;;

defineConfig({
  name: &#x27;myApp&#x27;,
  version: &#x27;1.0.0&#x27;,
  liveUpdate: {
    appId: &#x27;your-app-id&#x27;,
    channelId: &#x27;production&#x27;,
    serverUrl: &#x27;https://api.ionicjs.com&#x27;
  }
});

Example: Checking for and Applying Updates

import { LiveUpdate } from &#x27;@ionic-native/live-update&#x27;;

async function checkForUpdates() {
  const update = await LiveUpdate.check();
  if (update.available) {
    await LiveUpdate.apply(update);
  }
}

Note: Live Updates require an active internet connection to check for and apply updates.

Warning: Updates applied via Live Updates will not be reviewed by app stores, so ensure all updates are thoroughly tested before deployment.

5. Configuring Update Channels

Channel	Description	Usage
stable	Default channel for production releases	For stable, tested builds
beta	For pre-release testing	For early adopters and QA
canary	For bleeding-edge features	For developers testing new features

Example: Setting up a Beta Channel

const config = {
  update: {
    channel: 'beta',
    appVersion: '2.1.0-beta.1'
  }
};

Note: Update channels are managed via the Ionic Appflow dashboard or CLI.

Warning: Ensure all channel configurations are consistent across environments.

6. Implementing Force Update

Property	Description	Default Value	Notes
forceUpdate	Enables or disables force update functionality	`false`	When set to `true`, users must update the app to continue using it
updateUrl	URL to fetch the latest app version information	`null`	Required if force update is enabled
minVersion	Minimum version required to continue using the app	`null`	Must be in format `major.minor.patch`

Example: Configuring Force Update

const config = {
  forceUpdate: true,
  updateUrl: 'https://api.example.com/app-version',
  minVersion: '2.0.0'
};

// Apply config to Ionic app
Ionic.config.set('forceUpdate', config);

Example: Handling Force Update in App

import { AppVersion } from '@ionic-native/app-version';

async function checkForForceUpdate() {
  const currentVersion = await AppVersion.getVersionNumber();
  const requiredVersion = '2.0.0';

  if (compareVersions(currentVersion, requiredVersion) < 0) {
    // Show update dialog
    showUpdateDialog();
  }
}

function compareVersions(v1: string, v2: string): number {
  const [major1, minor1, patch1] = v1.split('.').map(Number);
  const [major2, minor2, patch2] = v2.split('.').map(Number);

  if (major1 > major2) return 1;
  if (major1 < major2) return -1;
  if (minor1 > minor2) return 1;
  if (minor1 < minor2) return -1;
  if (patch1 > patch2) return 1;
  if (patch1 < patch2) return -1;
  return 0;
}

Note: The forceUpdate feature requires a backend service to provide version information and must be implemented carefully to avoid breaking user experience.

7. Handling Update Prompts

Property	Description	Default	Notes
updatePrompt	Controls whether to show update prompt	`false`	Set to `true` to enable update prompts
updatePromptTitle	Title for update prompt dialog	`"Update Available"`	Customize the title of update prompt
updatePromptMessage	Message shown in update prompt	`"A new version of the app is available."`	Inform user about update
updatePromptButtonText	Text for update button	`"Update Now"`	Label for action button

Example: Configure Update Prompt

const config = {
  updatePrompt: true,
  updatePromptTitle: "New Version Available",
  updatePromptMessage: "Please update to the latest version for best experience.",
  updatePromptButtonText: "Update"
};

// Apply config in Ionic app

Note: Update prompts are only shown when the app is running in a browser or mobile environment where updates can be triggered.

8. Using Background Updates

Background updates in Ionic apps allow users to receive app updates without requiring them to manually download and install a new version. This feature is particularly useful for apps that need frequent updates or require real-time data synchronization.

Feature	Description	Status
Background Update	Enables automatic app updates in the background	NEW
Update Strategy	Defines how updates are applied (immediate, delayed)	NEW
Update Check Frequency	How often the app checks for updates (e.g., every 1 hour)	NEW

Example: Configuring Background Updates

import { Plugins } from '@capacitor/core';

const { BackgroundUpdate } = Plugins;

await BackgroundUpdate.configure({
  updateStrategy: 'immediate',
  checkFrequency: 'hourly'
});

Example: Handling Update Events

import { Plugins } from '@capacitor/core';

const { BackgroundUpdate } = Plugins;

BackgroundUpdate.addListener('updateAvailable', (event) => {
  console.log('Update available:', event);
});

BackgroundUpdate.addListener('updateDownloaded', (event) => {
  console.log('Update downloaded:', event);
});

Note: Background updates require appropriate permissions and platform-specific configurations to function correctly.

Warning: Ensure that your app's update strategy aligns with user expectations and network usage to avoid unexpected data consumption.

9. Rolling Back Updates

Example: Reverting to a Previous Version

ionic deploy rollback --channel production

Option	Values	Description
--channel	`production`, `staging`	Target deployment channel for rollback
--version	`v1.2.3`	Specific version to roll back to (optional)

Note: Rollback is supported only for ionic deploy managed updates.

Warning: Rolling back to a previous version may cause data inconsistencies if the app structure changed between versions.

10. Monitoring Update Analytics

Example: Tracking App Updates with Ionic Analytics

import { IonicAnalytics } from '@ionic/analytics';

IonicAnalytics.init({
  appId: 'your-app-id',
  apiKey: 'your-api-key'
});

// Track update events
IonicAnalytics.track('app_update', {
  version: '2.1.0',
  updateType: 'major',
  timestamp: Date.now()
});

Event Type	Description	Properties	Notes
app_update	Tracks when an app update is installed	`version`, `updateType`, `timestamp`	Use for analytics and user behavior tracking
update_failed	Tracks when an app update fails to install	`version`, `error`, `timestamp`	Helps identify update issues and rollback scenarios

Update Tracking Best Practices

Log update events with version and timestamp
Track failed updates to identify platform-specific issues
Use update type (major/minor/patch) to categorize impact