Instant Update

Description

Publish updates to your Alpha Anywhere mobile apps without re-submitting them to the App Store using Instant Update.

Discussion

The Instant Update feature allows you to update a Cordova App that has already been installed on a user's device without needing to submit the app to the Ionic Appflow or rebuild the application using Cordova CLI after you have made changes to the app and without having to re-submit the app to the App stores.

As soon as the user launches the app on their mobile device, the app will be instantly updated to the latest version of the app.

The first time you create a Cordova App from a UX component, you are creating a Baseline for this application. The Baseline app must be submitted to Ionic Appflow or built using Cordova CLI, and must then be submitted to the appropriate App Stores.

After you make changes to the app, the Cordova genie will prompt if you want to do an Update build, a new BaseLine build, or Roll-back to a previous update.

images/instantupdateBaseline.png

You can only use the Instant Update feature if you do not need to change any of the plugins used in your application0. If you need to change plugins, you will need to create a new Baseline application.

If you select to do an Update build, the Cordova genie will determine which files in your project have changed (relative to the Baseline build) and will upload file containing the changes to a server (either an Alpha Software Amazon S3 bucket or your own Amazon S3 bucket). When a user launches the app on their device, the app will automatically check if a new version is available and will instantly update itself to the new version.

If you release an Update to your app, and you find that this new version has introduced a bug, you can roll back to a prior version. When the user launches the app on their device, the app will instantly be downgraded to the specified previously released version.

To turn on the Instant Update feature, set the Enable Instant Update property to Yes.

images/instantupdate1.gif

Once you have enabled Instant Update the Instant update settings property is revealed.

images/InstantUpdate2.gif

The dialog for the Instant Update Settings is shown below:

images/InstantUpdate2.png

Update Settings

The options in this dialog are:

  • Patch location

    The options are AlphaSoftware or PrivateS3Bucket. The patch files are uploaded to a S3 server and are then downloaded to each device when the app is launched on the device.

    As a convenience you can select AlphaSoftware to use a bucket that has been configured by Alpha Software. When you select the AlphaSoftware location, you do not have to specify the S3 Storage connection string or the Base URL properties.

    For testing, using the AlphaSoftware option is fine, but for production applications, it is highly recommended that you set up your own private S3 bucket.

    images/InstantUpdate3.png
    If the 'PrivateS3Bucket' option is selected, additional properties are exposed.
  • S3 Storage connection string

    This is the storage connection string that points to your S3 bucket. To create storage connection strings, select the Tools, Storage connection strings menu item when the Web Control Panel has focus.

  • Base URL

    This is the base URL for items in your S3 bucket. It will be of the form:

    http://<your S3 bucket Name>.s3.amazonaws.com/
  • Path

    This property defines the folder structure within the Amazon S3 bucket where the files should be stored. For example:

    'instantupdates/myfiles/'
  • System Message

    This property can be set to -- None or Verbose If None is selected, the After update message (if defined) will still be shown. In Verbose mode, the following system messages are shown:

    • The current installed version number (shown when the app is launched)
    • App is running latest version message (if no update to the app is found)
    • App was updated message (if an update was found)
    • In Verbose mode, the user-defined After update message will also be shown.
    • Fatal errors are always shown.
  • After update message

    Message to display on the device if the version was updated when the app was launched. You message text can include the {version} placeholder to display the version number that the app was updated to.

  • Automatically check for update when App is started

    Defines whether or not a check for a new version should be performed when the app is launched. This option is enabled by default.

    If you turn off Automatically check for update when App is started, you must manually check for an updated using the {dialog.object}.instantUpdateRefresh() method.

    You can dynamically enable or disable this setting at runtime using the {dialog.object}.instantUpdateUseAutoUpdate() method.

  • Display first-time run wait message

    The first time you load a Cordova app (built using the Instant Update feature) on a device the app files must be unzipped and stored in a folder on the device. On most newer devices, this process happens quite quickly. However, on some older Android devices, it can take some time to unzip the files. It can appear to the user that the app is not responding.

    You can display a message to the user when the app is unzipping files for first time use by enabling the Display first-time run wait message property. The message should tell users that this is a one-time delay and that they must wait until the files have been prepared.

    When enabled, the First-time run message property is also exposed, which is used to customize the wait message.

How to Configure A Private S3 Bucket

The S3 bucket you specify must have a CORS policy set. Click the CORS Help hyperlink on the Instant Update Settings dialog for more information on CORS.

images/instantupdateCORS.jpg

You will also need to set a bucket policy to set the objects in the bucket to allow public read. The policy can be set in the Amazon AWS management console and it will look something like this:

{
    "Id": "Policy1513279106848",
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1513279094040",
            "Action": [
                "s3:GetObject"
            ],
            "Effect": "Allow",
            "Resource": "arn:aws:s3:::your-bucket-name/*",
            "Principal": "*"
        }
    ]
}

URL For AJAX Callbacks

When creating an Instant Update to an existing baseline application, you can now change the URL for Ajax callbacks by checking the Change AJAX URL property in the image shown below.

When you press the OK button, the Genie will prompt for a new AJAX callback URL.

The AJAX callback URL is set in the Cordova builder when you create he baseline version of your application. When you create an update you might want to change this URL so that users who are still running an older version of your APP are still making callbacks to the original location, while users who are running the latest version of your app will make callbacks to a new location.

Another reason why you may want to change the URL for AJAX callbacks is that you simply want to move the location where your App is hosted. For example, you might be migrating from on premises deployment to deploying in the Alpha Cloud.

images/instantupdate_changeurl.jpg

If you change the URL for AJAX callbacks be sure to also publish your app to that location!

Version Numbers

When you create an Instant Update to a Cordova application, each update is automatically give an internal version number. The internal version number is an integer that automatically increments each time a new Instant Update is created.

Now, you can also define your own version number for each Instant Update. The version number can use any numbering pattern that you want. (The Internal Version Number will also still be generated). In addition you can define a description for the Instant Update.

Your version number and description will make it easier if you need to roll back to a previous version to select the version to which you want to roll back.

images/PreRel2.jpg

Channels

By default, when you publish an Instant Update to your Cordova application, all of the users of your app will get the update as soon as they launch the app on their devices (assuming the app was designed with auto update turned on).

However, you may want to push an update to a small set of users, perhaps because you are still testing a new feature. This can easily be done by specifying a channel when you publish an Instant Update.

You will need to add a user interface to your app so that a user can select what channel they are on. By default, all users are on the Production channel. But a user may change their channel to (say) the Test channel. The JavaScript method you can use to allow a user to set their channel is:

{dialog.object}.setChannel(channelName);

When you publish an Instant Update, you specify for which channel the update is intended. For example, if you publish an Instant Update to the Test channel then a user who is on the default Production channel will not get an update when they re-launch the app on their device. However, a user who has changed their channel to the Test channel will get updated when they re-launch the app. If that user later changes their channel back to the Production channel, then when that user re-launches the app, they will be automatically switched to the latest Production version.

images/PreRel3.jpg
  • Channel Properties

    There are several properties available to configure a channel. These properties include:

    Property
    Description
    UX Component

    The UX Component to publish to the channel.

    URL for Ajax callbacks

    The URL for Ajax Callbacks for the channel.

    For example, on your <Default> (i.e. production channel), you might be using a component called 'MyApp'. But on the test channel, you might want to use a different UX component (for example 'MyAppV2').

    In the Instant Update dialog, when you create a new channel, the dialog also allows you to set properties for the channel (you can't set properties for the <Default> (i.e. production) channel.

    images/instantupdate_setchannelprops.jpg
  • When you click the Set Channel Properties dialog the following dialog appears:

    images/instantupdate_channelprops.jpg

Creating a new Baseline

If you need to add or remove plugins from your Cordova application, or want to update your application in the App Store to a newer build of your app, you need to create a new Baseline application. To create a new Baseline, you must select the option in the Instant Update window.

images/instantupdateBaseline2.png
images/instantupdateBaselineConfirm.png
Alpha Anywhere will prompt you to confirm creating a new Baseline build

This will expose the Cordova Builder dialog, where you can make changes to plugins and other settings.

When you create a new Baseline application, all future Instant Updates published for the application will only apply to the new Baseline build. Users using an older version of your application will need to install the new Baseline application in order to continue receiving updates distributed using Instant Update.

Methods

The following Instant Update methods are available in the UX Component:

  • {dialog.object}.instantUpdateRefresh()

    This method allows you to check for a new Instant Update version of an application without having to exit the app on the device and then re-launch it.

    The method is only available in a Cordova application that was build with the Instant Update feature enabled.

    Normally, after you publish an Instant Update to a Cordova application, users will not get the new version until they re-launch the application on their devices.

    Using this method, you can get a new version of the application without have to exit and re-launch the application.

    Example:

    {dialog.object}.instantUpdateRefresh();
  • {dialog.object}.instantUpdateUseAutoUpdate()

    This method allows you to enable or disable the automatic check for updates. If disabled, you must manually check for updates using the {dialog.object}.instantUpdateRefresh() method.

    {dialog.object}.instantUpdateUseAutoUpdate(false);
  • See {dialog.object}.instantUpdateUseAutoUpdate method for more info.

  • {dialog.object}.instantUpdateCheckForUpdate()

    This method allows you check if an update is available in a Cordova application that was build with the Instant Update feature enabled. Since this is an asynchronous operation, you need to provide the JavaScript success and the error callback functions.

    If a result is returned within a 5 second time-frame, the successCallback is called and passed an object with a result property that will be either true or false. If true, an update is available. If a timeout or any other error occurs the error callback is passed an error object or a string, depending on the error.

    This method can be useful if you have turned off auto updates and want to programmatically check if an update is available.

    var _successCallbackFunction = function(e) { 
        if(!e.result) { 
            //there is no update available
            alert('You are running the latest version');
            return false;
        }
        
        A5.msgBox.show('Notice','<div style="height: 1in; padding: 15pt;">An update for this application is available. 
        Click OK to install the update.</div>',
        [{name: 'ok', html: 'OK', value: 'ok'}],
        function(button) {if(button == 'ok') {
            setTimeout(function() {
                {dialog.object}.instantUpdateRefresh() //install the update
            },10)
        }
        });
        
    }
    
    var _errorCallbackFunction = function() { 
        alert('Could not determine if an update is available');
    }
    
    
    {dialog.object}.instantUpdateCheckForUpdate(_successCallbackFunction,_errorCallbackFunction);
  • See {dialog.object}.instantUpdateCheckForUpdate method for more information.

  • {dialog.object}.setChannel()

    Sets the Instant Update channel in an mobile application published with Instant Updated enabled.

    {dialog.object}.setChannel("Test");
  • See {dialog.object}.setChannel method for more information.

Videos

Using the Instant Update Feature in a Cordova Application

After you have created a Cordova application from a UX component, if you subsequently want to update the application you need to go through the entire release cycle again (i.e. build using Cordova CLI or Ionic Appflow, then submit to the appropriate App Store). However, if you enable the Instant Update feature when you build your application in the first place, you can make certain types of updates to your application without having to go through the release cycle again.

Instant Update can be used as long as you are not changing the application's plugins, storyboard images, etc. You can perform an Instant Update on an application as long as the changes are limited to the application's UX component.

In this video we show how the Instant Update feature operates.

2017-12-24