Using the Deploy API

While the Ionic Cordova plugin can handle all of your updates and perform them for you, sometimes you may want to customize how this works. Some examples of things you may want to do are:

  • Allow users to subscribe to different Channels for Beta Features, etc.
  • Manage the update process yourself (ex. Download updates on login, Apply updates on logout or Check for updates every 30 minutes)
  • Display what Channel the user is connected to

The Pro Client gives you access to everything you need to make these modifications, and it’s recommended that you always use the Pro Client instead of the Cordova plugin directly.

Try the New Improved Deploy Plugin

We’re excited to announce that we’ve released major update to the deploy plugin and Pro Client! The new version of the plugin was neccessary to support underlying changes to the cordova-plugin-ionic-webview in order to support Ionic 4 and it also brings with it a number of optimizations that we know users have been looking forward to for a long time and lays the foundation for more! The major updates include:

  • CDN - The new deploy plugin is backed by a CDN so that files are cached close to your users in edge locations and will reduce download times
  • Differential Updates - The previous version of the plugin shipped all the assets in you built www directory for every update. The new one only downloads files that have changed since the previous versions stored on the device which can reduce bandwidth by up to 90% and should increase download speeds as well.
  • OnResume Updates - Now users will be able to recieve app updates on resuming the app after it has been in the background for a long enough period of time. Previously updates were only installed if the app was fully closed and reopened now you can use the MIN_BACKGROUND_DURATION plugin variable to control how long the app needs to be in the background before the plugin considers it “closed” for the purposes of checking for an update.

How To Install the New Version

If you’re starting from a brand new app created with ionic start you can follow the setup instructions and you’ll get the new version. If you’re upgrading from a previous version you can follow this guide & tutorial video.

Methods

Pro.deploy contains many functions that can help you utilize Deploy inside of your app. Here’s a rundown of each:


configure

configure(config: DeployConfig): 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

Parameters:

Param Type Description
config DeployConfig The new configuration for the plugin on this device.

Returns: Promise<void>

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

getConfiguration

getConfiguration(): Promise<ConfigurationInfo>

description: Get info about the current configuration on the device.

since: v5.0.0

Returns: Promise<ConfigurationInfo> - Info about the currently applied configuration details.

const info = await Pro.deploy.getConfiguration()
console.log(info)
// {
//   'appId': 'abcd1234',
//   'channel': 'MY_CHANNEL_NAME',
//   'binaryVersion': 'X.X.X',
//   'debug': false,
//   'debug': false,
//   'updateMethod': 'auto',
//   'maxVersions': 3,
//   'minBackgroundDuration': 30,
//   'currentVersionId': 'xxxx-xxxx-xxxx-xxxx'
// }

sync

sync(options: SyncOptions): Promise<SnapshotInfo | undefined>

description: This function performs an entire standard check, download, extract, and reload cycle rather than having to program it yourself. This should be used most of the time unless you need to customize the flow.

since: v5.0.0

Parameters:

Param Type Description
options SyncOptions Options to call sync with to override the default update method.

Returns: Promise<SnapshotInfo | undefined> - The info of the currently applied update or undefined if there is no applied update.

async performAutomaticUpdate() {
  try {
    const currentVersion = Pro.deploy.getCurrentVersion();
    const resp = await Pro.deploy.sync({updateMethod: 'auto'});
    if (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.
    // Here's how we would log it to Ionic Pro Monitoring while also catching:

    // Pro.monitoring.exception(err);
  }
}

checkForUpdate

checkForUpdate(): Promise<CheckForUpdateResponse>

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

since: v5.0.0

Returns: Promise<CheckForUpdateResponse> - An object describing if an update is available.

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

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

Parameters:

Param 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 available update was successfully downloaded.


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

extractUpdate

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

description: Extract the files from an update downloaded with the downloadUpdate method to prepare for loading the app.

since: v5.0.0

Parameters:

Param 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 available update was successfully extracted.

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

reloadApp

reloadApp(): Promise<boolean>

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

since: v5.0.0

Returns: Promise<boolean> - true if the app was successfully reloaded.

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

getCurrentVersion

getCurrentVersion(): Promise<SnapshotInfo | undefined>

description: Get info about the currently deployed update.

since: v5.0.0

Returns: Promise<SnapshotInfo | undefined> - Info about the currently applied update or undefined if there isn’t one applied.

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

getAvailableVersions

getAvailableVersions(): Promise<SnapshotInfo[]>

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

since: v5.0.0

Returns: Promise<SnapshotInfo[]> - A list of updates stored locally on the device.

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

deleteVersionById

deleteVersionById(versionId: string): Promise<boolean>

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

since: v5.0.0

Parameters:

Param Type
versionId string

Returns: Promise<boolean> - true if the version was successfully deleted.

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


init

init(config: DeployConfig): 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.

deprecated: in v4.2.0 in favor of configure

Parameters:

Param Type Description
config DeployConfig The new configuration for the plugin on this device.

Returns: Promise<void>

async initDeploy() {
  const config = {
    'appId': 'YOUR_APP_ID',
    'channel': 'CHANNEL_NAME'
  }
  await Pro.deploy.init(config);
}

checkAndApply

checkAndApply(redirect: boolean, downloadProgressFunc: CallbackFunction, extractProgressFunc: CallbackFunction): Promise<string>

description: This function performs an entire standard check, download, extract, and reload cycle rather than having to program it yourself. This should be used most of the time unless you need to customize the flow.

deprecated: in v4.2.0 in favor of sync

Parameters:

Param Type Description
redirect boolean Whether or not to reload the app immediately if an update is available.
downloadProgressFunc CallbackFunction A function which will recieve calls with a number representing the progress of the download.
extractProgressFunc CallbackFunction A function which will recieve calls with a number representing the progress of the extract.

Returns: Promise<SnapshotInfo> - The info of the currently applied update

async performAutomaticUpdate() {
    try {
      const resp = await Pro.deploy.checkAndApply(true, function(progress){
          this.downloadProgress = progress;
      });

      if (resp.update){
        // We found an update, and are in process of redirecting you since you put true!
      }else{
        // No update available
      }
    } catch (err) {
      // We encountered an error.
      // Here's how we would log it to Ionic Pro Monitoring while also catching:

      // Pro.monitoring.exception(err);
    }
  }

check

check(): Promise<CheckForUpdateResponse>

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

deprecated: in v4.2.0 in favor of checkForUpdate

Returns: Promise<CheckForUpdateResponse>

async performManualUpdate() {
  const haveUpdate = await Pro.deploy.check()
  if (haveUpdate){
    // We have an update!
  }
}

download

download(progress?: CallbackFunction<string>): Promise<string>

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

deprecated: in v4.2.0 in favor of downloadUpdate

Parameters:

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

Returns: Promise<string>

public downloadProgress = 0;

async performManualUpdate() {
  const haveUpdate = await Pro.deploy.check()
  if (haveUpdate){
    this.downloadProgress = 0;

    await Pro.deploy.download((progress) => {
      this.downloadProgress = progress;
    })
  }
}

extract

extractUpdate(progress?: CallbackFunction<string>): Promise<string>

description: Extract the files from an update downloaded with the downloadUpdate method to prepare for loading the app.

deprecated: in v4.2.0 in favor of extractUpdate

Parameters:

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

Returns: Promise<string>

public downloadProgress = 0;
public extractProgress = 0;

async performManualUpdate() {
  const haveUpdate = await Pro.deploy.check()
  if (haveUpdate){
    this.downloadProgress = 0;
    this.extractProgress = 0;

    await Pro.deploy.download((progress) => {
      this.downloadProgress = progress;
    })
    await Pro.deploy.extract((progress) => {
      this.extractProgress = progress;
    })
  }
}

redirect

redirect(): Promise<string>

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

deprecated: in v4.2.0 in favor of reloadApp

Returns: Promise<string>

public downloadProgress = 0;
public extractProgress = 0;

async performManualUpdate() {
  const haveUpdate = await Pro.deploy.check()
  if (haveUpdate){
    this.downloadProgress = 0;
    this.extractProgress = 0;

    await Pro.deploy.download((progress) => {
      this.downloadProgress = progress;
    })
    await Pro.deploy.extract((progress) => {
      this.extractProgress = progress;
    })
    await Pro.deploy.redirect();
  }
}

info

info(): Promise<string>

description: Get the versionId of the currently deployed update.

deprecated: in v4.2.0 in favor of getConfiguration

Returns: Promise<string>

const info = await Pro.deploy.info()
console.log(info)
// { 
//   'deploy_uuid': 'UUID_OF_ACTIVE_CODE',
//   'channel': 'CHANNEL_NAME',
//   'binary_version': 'X.X.X'
// }

getVersions

getVersions(): Promise<string[]>

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

deprecated: in v4.2.0 in favor of getAvailableVersions

Returns: Promise<string[]>

async checkVersions() {
  const versions = await Pro.deploy.getVersions();
  console.log(versions);
  // ['UUID', 'UUID2', 'UUID3']
}

deleteVersion

deleteVersion(versionId: string): Promise<string>

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

deprecated: in v4.2.0 in favor of deleteVersionById

Parameters:

Param Type
versionId string

Returns: Promise<string>

async deleteVersion() {
  const versions = await Pro.deploy.getVersions();
  Pro.deploy.deleteVersion(versions[0]);
}

Interfaces

DeployConfig

Properties


<Optional> appId

● appId: undefined | string

The Ionic Pro app id.


<Optional> channel

● channel: undefined | string

The channel that the plugin should listen for updates on.


<Optional> debug

● debug: undefined | true | false

whether or not the app should in debug mode


CheckForUpdateResponse

Properties

available

● available: boolean

Whether or not an update is available.


<Optional> integrity

● integrity: undefined | string

The checksum of the manifest file.


<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.


SyncOptions

Properties

updateMethod

● updateMethod: 'background' | 'auto'

The update method to use when applying an update if available. This will override the default method the plugin was configured with temporarily.


ConfigurationInfo

Properties

  • binaryVersion <string> - The binary version of the native bundle.
  • channel <string> - The channel name the device is currently configured to check for updates on.
  • debug <boolean> - Whether the plugin is in debug mode or not.
  • updateMethod <'none' | 'auto' | 'background'> - The currently configured updateMethod for the plugin.
  • maxVersions <number> - The maximum number of updates to be stored locally on the device.
  • 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.
  • debug <boolean> - Whether the plugin is in debug mode or not.
  • currentVersionId <string | undefined> - The id of the currently applied update or undefined if none is applied.

SnapshotInfo

Properties

binaryVersion

● binaryVersion: string

The binary version the snapshot was downloaded for.


binary_version

● binary_version: string

deprecated: in favor of binaryVersion

The binary version the snapshot was downloaded for.


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.


CallbackFunction

Callable

__call(result?: T): void

A callback function to handle the result.

Parameters:

Param Type
Optional result T

Returns: void

Plugin Variables

When installing cordova-plugin-ionic there are a number of variables you can install the plugin with to configure the behavior of the plugin and how updates are applied to your app by using the --variable flag.

Example:

// use the MIN_BACKGROUND_DURATION variable
cordova plugin add cordova-plugin-ionic --variable MIN_BACKGROUND_DURATION=60 ...

APP_ID - Required

The APP_ID variable sets app in the pro dashboard the plugin should check for updates. The App ID can be updated at runtime via the Deploy Pro Client.

CHANNEL_NAME - Required

The CHANNEL_NAME variable sets which channel the plugin should check for updates. The Channel can be updated at runtime via the configure method of the Deploy Pro Client.

UPDATE_METHOD

Default: background

The UPDATE_METHOD determines how updates are applied to your app. When you are installing the Ionic Pro plugin, you have the option to choose which update method to use. The three options are:

background - mode will check for updates when a user first opens your app from a completely closed state (in the splashscreen) or after a user resumes the app from the background after the minimum duration. It will download the update in the background while the user is using your app. The next time they close and open your app, we will apply the updated version. You can still perform updates yourself and override the update method using the Deploy Pro Client as well.

auto - mode will check for updates when a user first opens your app from a completely closed state (in the splashscreen) or after a user resumes the app from the background after the minimum duration. It will then WAIT on the splashscreen until the new update is downloaded, and immediately show the user the new version of the code after the splashscreen. Using this method essentially forces users to always use the most up to date version when connected to the internet with the trade off that users may wait on the splashscreen longer before interacting with the app while waiting for an update. You can still perform updates yourself and override the update method using the Deploy Pro Client as well.

none - will not automatically apply or download updates for you. Instead you have to manage the entire update process yourself using the Deploy Pro Client. This isn’t recommended as if you deploy an update that “breaks” your app and can no longer apply Deploy updates, you will have to release a native binary in order to fix the issue or the user will have to delete and reinstall your app. Using the background or auto methods protects you by applying updates in the native layer.

MAX_STORE

Default: 2

The MAX_STORE variable can be configured to tell the deploy plugin how many updates to keep around locally on the device. Keeping more versions around locally makes rolling back faster but takes up more room on the device.

MIN_BACKGROUND_DURATION

New in v5 RC

Default: 30

The MIN_BACKGROUND_DURATION variable sets the minimum number of seconds the user needs to put the app in the background before the plugin considers the app closed and checks for an update on resume like it would on a fresh app open according to the specified update method.

API

Native

General