Using the Deploy API

Contents
Before you begin using the API you'll need to make sure you've already installed and configured the plugin. and you may want to use the Pro Client to make accessing the API easier.

While the Appflow SDK 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 plugin API directly.

Note: Async Await vs. ".then()"

In all of the examples on this page you'll notice that we use Async/Await. This automatically resolves promises inline for you and waits to perform the next action. This is just an alternative to using `.then`. Async/Await just allows your code to be much more legible (especially when you'd normally be chaining multiple promises) as it's read like a syncronous piece of code. Here are two ways to write the same piece of code:

Pro.deploy.getCurrentVersion().then((versionInfo) => {
  console.log(versionInfo);
})

// is the same as

async getVersionInfo(){
  const versionInfo = await Pro.deploy.getCurrentVersion();
  console.log(versionInfo);
}

Using the Ionic Pro Client

The Ionic Pro Client gives you access to the Deploy API inside of your app.

You simply need to install the latest version of the Pro Client:

npm install @ionic/[email protected]

Then you can import it in order to use the Deploy API in your code:

import { Pro } from '@ionic/pro';

How To Upgrade from v4 to v5

The following docs are for v5.x.x of the Appflow SDK. 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',
//   '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'
// }

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);
}

Interfaces

DeployConfig

Properties

  • appId (optional): undefined | string
    The Ionic Appflow app id.
  • channel (optional): undefined | string
    The channel that the plugin should listen for updates on.
  • maxVersions (optional): undefined | number
    The number of previous updates to be cached on the device
  • minBackgroundDuration (optional): 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.
  • updateMethod (optional): undefined | background | none | auto
    The update method the app should use when checking for available updates

CheckForUpdateResponse

Properties

  • available: boolean
    Whether or not an update is available.
  • incompatibleUpdateAvailable: boolean
    Whether or not an update that is not compatible with this device is available.
  • snapshot (optional): undefined | string
    The id of the snapshot, if available.
  • build (optional): undefined | string
    The id of the build, if available.

SyncOptions

Properties

  • 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

  • binaryVersionName: string
    The versionName on Android or CFBundleShortVersionString on iOS this is the end user readable version listed on the stores.
  • binaryVersionCode: string (iOS) | number (Android)
    The versionCode on Android or CFBundleVersion on iOS this should be changed every time you do a new build.
  • channel: string
    The channel name the device is currently configured to check for updates on.
  • disabled: boolean
    Whether the deploy updates are disabled 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.
  • currentVersionId: string | undefined
    The version id of the currently applied update or undefined if none is applied.
  • currentBuildId: string | undefined
    The build id of the currently applied update or undefined if none is applied.

SnapshotInfo

Properties

  • binaryVersion: string
    The binary version the snapshot was downloaded for.
  • channel: string
    The channel that the snapshot was downloaded for..
  • 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 the Appflow SDK (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 configure method.

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.

Plugin Preferences

DisableDeploy

Default: false

Allows to disable deploy updates by adding this preference in the config.xml

<preference name="DisableDeploy" value="true" />

After adding be sure to run cordova prepare [platform] in order for changes to take effect.

Channels Tutorials and Videos