Live Update API

Installation and Usage

The Live Update API offers programmatic access to the Live Update SDK and the most control over the user experience. In order to use the Live Update API inside of your app, you need to install the latest version of the Live Update SDK and set the UPDATE_METHOD to none:

ionic deploy add --update-method=none --app-id="YOUR_APP_ID" --channel-name="YOUR_CHANNEL_NAME"

Then you can import the Live Update API in order to it in your code:

// ES2015/Typescript
import { Deploy } from 'cordova-plugin-ionic';

...

async changeToBetaChannel() {
  await Deploy.configure({channel: 'BETA'});
}

...

// Angular
import { Deploy } from 'cordova-plugin-ionic/dist/ngx';

...

constructor(private deploy: Deploy) {
  ...
}

async changeToBetaChannel() {
  await this.deploy.configure({channel: 'BETA'});
}

...

Plugin Configuration

The Live Update SDK uses variables to configure the way the plugin behaves. View configuration options.

API Index

Classes

IonicDeploy

Classes

IonicDeploy

IonicDeploy:

The Ionic Live Update Plugin API

usage:

async performManualUpdate() {
 const update = await Deploy.checkForUpdate()
 if (update.available){
   // We have an update!
 }
}

Methods

The plugin contains many functions that can help you utilize Deploy inside of your app.

configure
getConfiguration
sync
checkForUpdate
downloadUpdate
extractUpdate
reloadApp
getCurrentVersion
getVersionById
getAvailableVersions
deleteVersionById

checkForUpdate

▸ checkForUpdate(): Promise<CheckForUpdateResponse>

description: Check for available updates for the currently configured app id and channel.

since: v5.0.0

usage:

async performManualUpdate() {
 const update = await Deploy.checkForUpdate()
 if (update.available){
   // We have an update!
 }
}

Returns: Promise<CheckForUpdateResponse> A response describing an update if one is available.

configure

▸ configure(config: IDeployConfig): Promise<void>

description: Update the default configuration for the plugin on the current device. The new configuration will be persisted across app close and binary updates.

since: v5.0.0

usage:

async configureDeploy() {
 const config = {
   'appId': 'YOUR_APP_ID',
   'channel': 'CHANNEL_NAME'
 }
 await Deploy.configure(config);
}

Parameters:

Name	Type	Description
config	IDeployConfig	The new configuration for the plugin on this device.

Returns: Promise<void>

deleteVersionById

▸ deleteVersionById(version: string): Promise<boolean>

description: Remove the files specific to a snapshot from the device.

usage:

async deleteVersion() {
 const versions = await Deploy.getAvailableVersions();
 Deploy.deleteVersionById(versions[0].versionId);
}

Parameters:

Name	Type	Description
version	`string`	The versionId

Returns: Promise<boolean> true if the update was deleted.

downloadUpdate

▸ downloadUpdate(progress?: CallbackFunction<number>): Promise<boolean>

description: Download the new files from an available update found by the checkForUpdate method and prepare the update.

since: v5.0.0

usage:

async performManualUpdate() {
 const update = await Deploy.checkForUpdate()
 if (update.available){
   await Deploy.downloadUpdate((progress) => {
     console.log(progress);
   })
 }
}

Parameters:

Name	Type	Description
`Optional` progress	CallbackFunction<`number`>	A progress callback function which will be called with a number representing the percent of completion of the download and prepare.

Returns: Promise<boolean> true if the download succeeded

extractUpdate

▸ extractUpdate(progress?: CallbackFunction<number>): Promise<boolean>

description: Extract a downloaded bundle of updated files.

since: v5.0.0

usage:

async performManualUpdate() {
 const update = await Deploy.checkForUpdate()
 if (update.available){
   await Deploy.downloadUpdate((progress) => {
     console.log(progress);
   })
   await Deploy.extractUpdate((progress) => {
     console.log(progress);
   })
 }
}

Parameters:

Name	Type	Description
`Optional` progress	CallbackFunction<`number`>	A progress callback function which will be called with a number representing the percent of completion of the extract.

Returns: Promise<boolean> true if the extract succeeded

getAvailableVersions

▸ getAvailableVersions(): Promise<ISnapshotInfo[]>

description: Get a list of the snapshots available on the device.

since: v5.0.0

usage:

async checkVersions() {
const versions = await Deploy.getAvailableVersions();
console.log(versions);
// [
//   {
//     'versionId': 'versionId1',
//     'channel': 'CHANNEL_NAME',
//     'binaryVersion': '1.0.1'
//   },
//   {
//     'versionId': 'versionId2',
//     'channel': 'CHANNEL_NAME',
//     'binaryVersion': '1.0.1'
//   },
// ]

Returns: Promise<ISnapshotInfo[]> a list of available updates.

getConfiguration

▸ getConfiguration(): Promise<ICurrentConfig>

description: Get the current configuration for the plugin on the current device.

since: v5.0.0

usage: `typescript const info = Deploy.getConfiguration() console.log(info) // { // 'appId': 'abcd1234', // 'channel': 'MY_CHANNEL_NAME', // 'binaryVersionName': 'X.X.X', // 'binaryVersionCode': 'X.X.X', (string on iOS number on Android) // 'disabled': false, // 'updateMethod': 'auto', // 'maxVersions': 3, // 'minBackgroundDuration': 30, // 'currentVersionId': 'xxxx-xxxx-xxxx-xxxx' // 'currentBuildId' : 'xxxxxxx' // }

Returns: Promise<ICurrentConfig> The current configuration of the plugin.

getCurrentVersion

▸ getCurrentVersion(): Promise<ISnapshotInfo | undefined>

description: Get info about the currently deployed update or undefined if none are applied.

since: v5.0.0

usage:

const info = await Deploy.getCurrentVersion()
console.log(info)
// {
//   'versionId': 'UUID_OF_ACTIVE_CODE',
//   'channel': 'CHANNEL_NAME',
//   'binaryVersion': 'X.X.X'
// }

Returns: Promise<ISnapshotInfo | undefined> The info about the currently applied update or undefined if none is applied.

getVersionById

▸ getVersionById(versionId: string): Promise<ISnapshotInfo>

description: Get info about the update by its versionId

since: v5.0.0

Parameters:

Name	Type
versionId	`string`

Returns: Promise<ISnapshotInfo> The info about the currently applied update or undefined if none is applied.

reloadApp

▸ reloadApp(): Promise<boolean>

description: Reload the app if a more recent version of the app is available.

since: v5.0.0

usage:

async performManualUpdate() {
 const update = await Deploy.checkForUpdate()
 if (update.available){
   await Deploy.downloadUpdate((progress) => {
     console.log(progress);
   })
   await Deploy.extractUpdate((progress) => {
     console.log(progress);
   })
   await Deploy.reloadApp();
 }
}

Returns: Promise<boolean> true if the reload succeeded

sync

▸ sync(syncOptions?: ISyncOptions, progress?: CallbackFunction<number>): Promise<ISnapshotInfo | undefined>

description: Check for an update, download it, and apply it in one step.

since: v5.0.0

usage:

async performAutomaticUpdate() {
 try {
   const currentVersion = await Deploy.getCurrentVersion();
   const resp = await Deploy.sync({updateMethod: 'auto'}, percentDone => {
     console.log(`Update is ${percentDone}% done!`);
   });
   if (!currentVersion || currentVersion.versionId !== resp.versionId){
     // We found an update, and are in process of redirecting you since you put auto!
   }else{
     // No update available
   }
 } catch (err) {
   // We encountered an error.
 }
}

Parameters:

Name	Type	Default value	Description
`Default value` syncOptions	ISyncOptions	{}	(Optional) Application update overrides.

Returns: Promise<ISnapshotInfo | undefined> The info about the currently applied update or undefined if none is applied.

Interfaces

CallbackFunction

▸ __call(result?: [T]()): void

A callback function to handle the result.

Parameters:

Name	Type
`Optional` result	[T]()

Returns: void

CheckForUpdateResponse

CheckForUpdateResponse:

The response object describing if an update is available.

available

● available: boolean

Whether an update is available.

`<Optional>` build

● build: undefined | string

The id of the build if available.

compatible

● compatible: boolean

Equivalent to available since v5 this can be ignored in favor of available

deprecated:

`<Optional>` incompatibleUpdateAvailable

● incompatibleUpdateAvailable: undefined | false | true

Whether there is an update available that is not compatible with this device.

partial

● partial: false

Legacy indicator of whether the update is a partial one. This will always be false and can be ignored

deprecated:

`<Optional>` snapshot

● snapshot: undefined | string

The id of the snapshot if available.

`<Optional>` url

● url: undefined | string

The url to fetch the manifest of files in the update.

IAppInfo

IAppInfo:

Information about the application.

binaryVersionCode

● binaryVersionCode: string | number

The versionCode on Android or CFBundleVersion on iOS this should be changed every time you do a new build debug or otherwise.

binaryVersionName

● binaryVersionName: string

The versionName on Android or CFBundleShortVersionString on iOS this is the end user readable version listed on the stores.

bundleName

● bundleName: string

The bundle name.

bundleVersion

● bundleVersion: string

deprecated: The versionName on Android or CFBundleShortVersionString on iOS this is the end user readable version listed on the stores.

dataDirectory

● dataDirectory: string

Directory where the snapshots are stored

device

● device: string

A generated device ID (NOT a native device ID)

platform

● platform: "ios" | "android"

The platform that the app is currently installed on.

platformVersion

● platformVersion: string

The version of the native platform.

version

● version: string

deprecated: The versionCode on Android or CFBundleVersion on iOS this should be changed every time you do a new build debug or otherwise.

ICurrentConfig

ICurrentConfig:

The current configuration for the deploy plugin on the device.

appId

● appId: string

The Ionic Appflow app id.

binaryVersion

● binaryVersion: string

deprecated: The binary version of the native bundle versionName on Android or CFBundleShortVersionString on iOS deprecated in favor of versionName

binaryVersionCode

● binaryVersionCode: string

The build version code of the native bundle versionCode on Android or CFBundleVersion on iOS

binaryVersionName

● binaryVersionName: string

The binary version of the native bundle versionName on Android or CFBundleShortVersionString on iOS

channel

● channel: string

The channel that the plugin should listen for updates on.

`<Optional>` currentBuildId

● currentBuildId: undefined | string

The id of the currently applied build or undefined if none is applied.

`<Optional>` currentVersionId

● currentVersionId: undefined | string

The id of the currently applied updated or undefined if none is applied.

disabled

● disabled: boolean

Whether the user disabled deploy updates or not.

host

● host: string

The host API the plugin is configured to check for updates from.

maxVersions

● maxVersions: number

The maximum number of updates to be stored locally on the device.

minBackgroundDuration

● minBackgroundDuration: number

The number of seconds the app needs to be in the background before the plugin considers it closed for the purposes of fetching and applying a new update.

updateMethod

● updateMethod: "none" | "auto" | "background"

The currently configured updateMethod for the plugin.

IDeployConfig

IDeployConfig:

The configuration for the deploy plugin on the device.

`<Optional>` appId

● appId: undefined | string

The Ionic app id.

`<Optional>` channel

● channel: undefined | string

The channel that the plugin should listen for updates on.

`<Optional>` debug

● debug: undefined | false | true

Whether the app should run in debug mode

`<Optional>` maxVersions

● maxVersions: undefined | number

The number of previous updates to be cached on the device

`<Optional>` minBackgroundDuration

● minBackgroundDuration: undefined | number

The number of seconds the app should be in the background for before the plugin considers it closed and checks for an updated on resume of the app.

`<Optional>` updateMethod

● updateMethod: "none" | "auto" | "background"

The update method the app should use when checking for available updates

ISnapshotInfo

ISnapshotInfo:

Information about a snapshot

binaryVersion

● binaryVersion: string

deprecated: The binary version the snapshot was downloaded for. The versionName on Android or CFBundleShortVersionString on iOS this is the end user readable version listed on the stores.

binaryVersionCode

● binaryVersionCode: string

The binary version build code the snapshot was downloaded for. The versionCode on Android or CFBundleVersion on iOS this should be changed every time you do a new build debug or otherwise.

binaryVersionName

● binaryVersionName: string

The binary version name the snapshot was downloaded for. The versionName on Android or CFBundleShortVersionString on iOS this is the end user readable version listed on the stores.

binary_version

● binary_version: string

deprecated: in favor of binaryVersion

The binary version the snapshot was downloaded for.

buildId

● buildId: string

The id for the snapshot.

channel

● channel: string

The channel that the snapshot was downloaded for..

deploy_uuid

● deploy_uuid: string

deprecated: in favor of versionId

The id for the snapshot.

versionId

● versionId: string

The id for the snapshot.

ISyncOptions

ISyncOptions:

Configuration options for the call to sync

`<Optional>` updateMethod

● updateMethod: "background" | "auto"

Whether the update should be applied immediately or on the next app start.

Installation and Usage​

Plugin Configuration​

API Index​

Classes​

Interfaces​

Classes​

IonicDeploy​

Methods​

checkForUpdate​

configure​

deleteVersionById​

downloadUpdate​

extractUpdate​

getAvailableVersions​

getConfiguration​

getCurrentVersion​

getVersionById​

reloadApp​

sync​

Interfaces​

CallbackFunction​

CheckForUpdateResponse​

available​

<Optional> build​

compatible​

<Optional> incompatibleUpdateAvailable​

partial​

<Optional> snapshot​

<Optional> url​

IAppInfo​

binaryVersionCode​

binaryVersionName​

bundleName​

bundleVersion​

dataDirectory​

device​

platform​

platformVersion​

version​

ICurrentConfig​

appId​

binaryVersion​

binaryVersionCode​

binaryVersionName​

channel​

<Optional> currentBuildId​

<Optional> currentVersionId​

disabled​

host​

maxVersions​

minBackgroundDuration​

updateMethod​

IDeployConfig​

<Optional> appId​

<Optional> channel​

<Optional> debug​

<Optional> maxVersions​

<Optional> minBackgroundDuration​

<Optional> updateMethod​

ISnapshotInfo​

binaryVersion​

binaryVersionCode​

binaryVersionName​

binary_version​

buildId​

channel​

deploy_uuid​

versionId​

ISyncOptions​

<Optional> updateMethod​

Installation and Usage

Plugin Configuration

API Index

Classes

Interfaces

Classes

IonicDeploy

Methods

checkForUpdate

configure

deleteVersionById

downloadUpdate

extractUpdate

getAvailableVersions

getConfiguration

getCurrentVersion

getVersionById

reloadApp

sync

Interfaces

CallbackFunction

CheckForUpdateResponse

available

`<Optional>` build

compatible

`<Optional>` incompatibleUpdateAvailable

partial

`<Optional>` snapshot

`<Optional>` url

IAppInfo

binaryVersionCode

binaryVersionName

bundleName

bundleVersion

dataDirectory

device

platform

platformVersion

version

ICurrentConfig

appId

binaryVersion

binaryVersionCode

binaryVersionName

channel

`<Optional>` currentBuildId

`<Optional>` currentVersionId

disabled

host

maxVersions

minBackgroundDuration

updateMethod

IDeployConfig

`<Optional>` appId

`<Optional>` channel

`<Optional>` debug

`<Optional>` maxVersions

`<Optional>` minBackgroundDuration

`<Optional>` updateMethod

ISnapshotInfo

binaryVersion

binaryVersionCode

binaryVersionName

binary_version

buildId

channel

deploy_uuid

versionId

ISyncOptions

`<Optional>` updateMethod