PhoneGap Build 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 PhoneGap App that has already been installed on a user's device without needing to submit the app to the PhoneGap Build service 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 PhoneGap App from a UX component, you are creating a Baseline for this application. The Baseline app must be submitted to the PhoneGap Build service, and must then be submitted to the appropriate App Stores.

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

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

If you select to do an Update build, the PhoneGap 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.

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

The dialog for the Instant Update Settings is shown below:

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.

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

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

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

Channels 

By default, when you publish an Instant Update to your PhoneGap 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.

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

  • When you click the Set Channel Properties dialog the following dialog appears:

Creating a new Baseline 

If you need to add or remove plugins from your PhoneGap 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.

Alpha Anywhere will prompt you to confirm creating a new Baseline build

This will expose the PhoneGap Build 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 PhoneGap application that was build with the Instant Update feature enabled.

    Normally, after you publish an Instant Update to a PhoneGap 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 PhoneGap 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 PhoneGap Application

After you have created a PhoneGap 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. submit to PhoneGap Build, 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 PhoneGap plugins used by your application, or the splash screens, etc. You can perform an Instant Update on an application as long as the changes to the application are limited to changes in the application's UX component.

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

2017-12-24