Skip to main content

Install the Live Update SDK

In order to take advantage of deploying live updates to your app and bypassing the app stores, you'll need to install the Live Update SDK. The Live Update SDK comes with Appflow's Live Update feature for detecting and syncing your app with updates that you've pushed to channels.

To install the Live Update SDK plugin from the Dashboard, follow the instructions provided by clicking "Install Instructions" on the Destinations list in the Appflow Dashboard under "Deploy".

Destinations represent services where you can send build artifacts, including Live Update Channels. By default, a Production Live Update Channel is created for you.

Install Instructions

Installing the Live Update SDK Manually

To install the plugin manually, run the following command in the root directory of your Ionic app, making sure to substitute the correct values for your app:

ionic deploy add  \
    --app-id="YOUR_APP_ID" \
    --channel-name="YOUR_CHANNEL_NAME" \
    --update-method="background|auto|none" \

You can also run ionic deploy add and the CLI will prompt you for the neccessary values.

note

The plugin delays the Cordova deviceready event until it finishes checking for updates and sets the AutoHideSplashScreen Cordova preference to false in the config.xml, which means the Splash Screen will not go away automatically. All Ionic templates run this.splashScreen.hide(); on the Cordova deviceready event by default, but if it was removed it should be added back.

Alternatively, the app can set the AutoHideSplashScreen Cordova preference to true in you config.xml to override the value added by the plugin, but that can lead to the Splash Screen going away before the download is complete.

Plugin Configuration

The Live Update SDK uses variables to configure the way the plugin behaves. You can set these values when you add the plugin using flags (if using the ionic deploy add command) or using cordova variables (if using ionic cordova plugin add).

App ID

  • Required
  • The app id is required to receive updates for an app in the Appflow dashboard. You can find the id on the app overview page.
  • ionic deploy add --app-id=abcdef12
  • ionic cordova plugin add cordova-plugin-ionic --variable APP_ID=abcdef12

Find the App Id on the App Overview page

Channel Name

  • Required
  • The channel name is required to receive updates for an app in the Appflow dashboard and indicates the channel from which the device will receive updates. Note this can also be updated programatically at runtime for advanced use cases. Make sure to use the exact name of your channel, including the exact casing!
  • ionic deploy add --channel-name=Production
  • ionic cordova plugin add cordova-plugin-ionic --variable CHANNEL_NAME=Production

Update Method

  • Default background
  • The update method determines how the app will check for and apply live updates from Appflow. Possible values are:
    • background (Recommended) - The app will check for updates in the background and not prolong the amount of time the splash screen is shown. If an update is available it will be downloaded and installed while the user is using the older version. The next time they launch the app or the app has been in background for the duration specified my min-background-duration the new version will be loaded.
    • auto - The app will delay the launch of the app by extending how long the splash screen is shown while downloading any available updates. Once the update is available, the new version will be immediately shown and the splash screen will be hidden. We generally don't recommend this mode since it can lead to the splash screen showing for a long time particularly if the user is on a poor network connection.
    • none - The plugin will not check for or apply updates on its own. This option offers the most control over the user experience since all update logic is applied programatically using the Live Update API.
  • ionic deploy add --update-method=background
  • ionic cordova plugin add cordova-plugin-ionic --variable UPDATE_METHOD=background

Max Versions

  • Default 2
  • This tells the plugin the number of previous updates it should keep on the device in order to speed up the rollback process if ever needed.
  • ionic deploy add --max-versions=2
  • ionic cordova plugin add cordova-plugin-ionic --variable MAX_STORE=2

Min Background Duration

  • Default 30
  • This tells the plugin the number of seconds the app needs to be in the background for it to have been considered "closed." If the app has been in the background for at least this duration the plugin will check for and apply updates according to the update method as if the app were opened from a fully closed state. This is helpful for triggering updates even when a user never fully closes the app but also allowing them to page over to another app or password manager for short periods of time without triggering an update.
  • ionic deploy add --min-background-duration=60
  • ionic cordova plugin add cordova-plugin-ionic --variable MIN_BACKGROUND_DURATION=60

Commit your changes

After you've installed the plugin, be sure to commit the changes made to your config.xml and package.json files.

git add . # stage any changes
git commit -m "added live update sdk" #  commit staged changes