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 App. 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 a changes file 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 it 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.

 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.

 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.

 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