Document TOP » API Reference » Monaca Power Plugins » Monaca In-App Updater

Monaca In-App Updater

This plugin updates HTML5 assets contained in the app without rebuilding and packaging the app. You need a Web server to host the update files which will be accessed from the app.

Note

In order to use this plugin, you are required to subscribe to a valid plan. Please refer to Pricing page.

This plugin is used differently depending on the Cordova version of your project:

For Cordova 6.2 Projects

Supported Platforms

  • iOS 8 or later
  • Android 4 or later

Adding the Plugin in Monaca Cloud IDE

  1. From Monaca Cloud IDE menu, go to File ‣ Manage Cordova Plugins or Config ‣ Manage Cordova Plugins.
  2. Click Enable button of the Monaca In-App Updater (Version 4.0.0) to add it into your project.
../../../_images/818.png
  1. Next, you need to configure necessary information for this plugin. Find your newly added plugin under the Enable Plugins section. Then, hover the plugin and click Configure button.
../../../_images/916.png
  1. Input the CheckUpdate URL and Download URL appropriately. Then, click OK button.
../../../_images/1015.png

Plugin Configuration

In this section, we will talk about how to create the two web API you will need to use this plugin: /checkUpdate and /download.

/checkUpdate

Check the update version on the server side.

Request Parameters

Parameter Data Type Description
project_id String Unique project ID
my_update_number String [optional] The current update number of the app
os String [optional] The type of OS to receive the update
build_type String [optional] The type of build
app_version String [optional] The version of the app
plugin_version String [optional] The version of the In-App-Updater plugin

Response Parameters

Here is an example of a successful response:

{
  "ios": {
    "2.1.0": { // app version
      "1": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/ios-v2.1.0.zip" // This parameter is optional.
      }
    }
  }
}

If you use static files, then the information of all update versions will be included in the response as follows:

{
  "ios": {
    "2.1.0": { // app version
      "1": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/1/ios-v2.1.0.zip" //  This parameter is optional.
      },
      "2": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/2/ios-v2.1.0.zip" //  This parameter is optional.
      }
    },
    "2.2.0": { // app version
      "1": { // update number
        "date": 20170210,
        "url": "https://hogehoge.com/app/1/ios-v2.2.0.zip" //  This parameter is optional.
      }
    }
  }
}

As shown in the above example, the value of the update number is an JSON object consists of the update information such as date, url and so on. It can be obtained by the updateInfo parameter of a JSON object returned by the Promise of getServerVersion() method.

/download

Download the zip file (update package file).

Note

You can omit this preference if you set a download URL with download().

Request Parameters

Parameter Data Type Description
update_number String The update version number to be downloaded
project_id String Unique project ID
my_update_number String [optional] The current update number of the app
os String [optional] The type of OS to receive the update
build_type String [optional] The type of build
app_version String [optional] The version of the app
plugin_version String [optional] The version of the In-App-Updater plugin

Response Parameters

A successful response contains a ZIP file of InAppUpdater resource.

Methods

The easiest way to use this plugin is to only use autoUpdate() which will download the update files (as configure in Plugin Configuration) and update the app automatically.

On the other hand, if you want to customize the update process, you can use various available methods such as getServerVersion(), download(), updateAndRestart() and so on.

Here is the list of all available methods for this plugin:

Methods Description
getServerVersion() Get the information of files to be updated from the server.
forceStopGetServerVersion() Force getServerVersion() to stop.
getLocalVersion() Get the currect version of the app.
download() Download the update files.
forceStopDownload() Force download() to stop.
updateAndRestart() Deploy and mount the downloaded update files, and then restart the app.
status() Get the current status of the plugin.
showAlertDialog() Show a dialog with a title and a message. Only one dialog is shown at a time.
dismissAlertDialog() Close the Alert dialog.
showProgressDialog() Show a Progress dialog indicating the update progress.
changeProgressDialog() Change the Progress dialog.
dismissProgressDialog() Close a Progress dialog.
networkStatus() Check the network status (Wifi, 3G/LTE, or disconnected).
terminateApp() Terminate/Shut down the app.
autoUpdate() Update automatically if necessary, by using methods such as getServerVersion, download, etc.

getServerVersion()

Get the information of files to be updated from the server.

monaca.InAppUpdater.getServerVersion([args: JSON object]): Promise

Parameter: JSON Object
Name Data Type Description
connectDelay Integer A delay time in milliseconds before starting to connect to the server
connectTimeout Integer (Android only) A time-out duration in milliseconds for connecting to the server
readTimeout Integer (Android only) A time-out duration in milliseconds for receiving all responses from the server
timeoutForRequest Integer (iOS only) A time-out duration in milliseconds for sending a request to the server. When the time-out happens, the request will be resent automatically without any errors.
timeoutForResponse Integer (iOS only) A time-out duration in milliseconds for receiving all responses from the server
Return Value: Promise
  • Success callback receives a JSON object as shown below:

    Name Data Type Description
    needsUpdate Boolean It indicates whether or not the version of the app should be updated.
    updatable Boolean It indicates whether or not there are new files for update on the server.
    latestVersion String The latest version of the app
    myVersion String The current version of the app
    latestUpdateNumber String The latest update number for the current version of the app
    myUpdateNumber String The current update number for the current version of the app
    updateInfo JSON Object

    The update information returned by the server after the update number. For example, if the server side response is as follows:

    {
      "ios": {
        "2.1.0": { // app version
          "1": { // update number
            "date": 20170113,
            "url": "https://hogehoge.com/app/ios-v2.1.0.zip" // This parameter is optional.
          }
        }
      }
    }
    

    Then, the value of updateInfo will be:

    updateInfo = {
      "date": 20170113,
      "url": "https://hogehoge.com/app/ios-v2.1.0.zip"
    }
    
  • Fail callback receives a JSON object indicating the error(s).

Example
monaca.InAppUpdater.getServerVersion().then(
    function(json) {
        alert( JSON.stringify(json) );
        targetVersion = json.myVersion;
        targetUpdateNumber = json.latestUpdateNumber;
        url = json.updateInfo.url;
        alert( targetVersion );
        alert( targetUpdateNumber );
        alert( url );
    } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

forceStopGetServerVersion()

Force getServerVersion() to stop.

monaca.InAppUpdater.forceStopGetServerVersion(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.forceStopGetServerVersion().then(
    function(str) { alert("stop success"); } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

getLocalVersion()

Get the currect version of the app.

monaca.InAppUpdater.getLocalVersion(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.getLocalVersion().then(
    function(json) { alert( JSON.stringify(json) ); } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

download()

Download the update files.

monaca.InAppUpdater.download(args: JSON object): Promise

Parameter: JSON Object
Name Data Type Description
updateNumber Integer The update number
bufferSize Integer (Android only) Buffer size in bytes. The default value is 8192.
url String The URL where you download the ZIP file from. If this value is not existed, the value of monaca:updater_DownloadUrl in config.xml is used instead.
connectDelay Integer A delay time in milliseconds before starting to connect to the server
connectTimeout Integer (Android only) A time-out duration in milliseconds for connecting to the server
readTimeout Integer (Android only) A time-out duration in milliseconds for receiving all responses from the server
timeoutForRequest Integer (iOS only) A time-out duration in milliseconds for sending a request to the server. When the time-out happens, the request will be resent automatically without any errors.
timeoutForResponse Integer (iOS only) A time-out duration in milliseconds for receiving all responses from the server
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
  • Progress callback receives a JSON object indicating the progress of download as shown below:
Name Data Type Description
count Integer The total size of the files that have been downloaded so far
total Integer The total size of the all expected download files
Example
monaca.InAppUpdater.download( { version : targetVersion, buildNumber : targetBuildNumber, url : url } ).then(
    function(json) { alert( JSON.stringify(json) ); } ,
    function(fail) { alert( JSON.stringify(fail) ); } ,
    function(json) { console.log( json.count + "/" + json.total + " are done." ); }
);

forceStopDownload()

Force download() to stop.

monaca.InAppUpdater.forceStopDownload(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.forceStopDownload().then(
    function(str) { alert("stop success"); } ,
    function(fail) { alert( JSON.stringify(fail) ); }
);

updateAndRestart()

Deploy and mount the downloaded update files, and then restart the app.

monaca.InAppUpdater.updateAndRestart(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
  • Progress callback receives a JSON object indicating the progress of the deployment as shown below:
Name Data Type Description
count Integer The total size of the files that have been deployed so far
total Integer The total size of the all update files to be deployed
Example
monaca.InAppUpdater.updateAndRestart().then(
    function() { },
    function(fail) { alert( JSON.stringify(fail) ); },
    function(json) { console.log( json.count + "/" + json.total + " are done." ); }
);

status()

Get the current status of the plugin.

monaca.InAppUpdater.status(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object as shown below:
Name Data Type Description
running Boolean Returns true if the plugin is in use.
status String The information on what kind of task the plugin is working on right now.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.status().then(
    function(json) { alert( JSON.stringify(json) ); },
    function(fail) { alert( JSON.stringify(fail) ); }
);

showAlertDialog()

Show a dialog with a title and a message. Only one dialog is shown at a time.

monaca.InAppUpdater.showAlertDialog(args: JSON object): Promise

Parameter: JSON Object
Name Data Type Description
title String Title of the dialog
message String Message content
button JSON Object

A button in the dialog consists of 2 elements such as :

  • label: [String] The label of the button
  • handler: A function to be called when the button is clicked.

Example:

{
    label : "OK",
    handler : function() { alert("OK is clicked"); }
}
cancel JSON Object

A cancel button in the dialog consists of 2 elements such as :

  • label: [String] The label of the cancel button
  • handler: A function to be called when the cancel button is clicked.

Example:

{
    label : "Close",
    handler : function() { alert("Close is clicked"); }
}
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.showAlertDialog({
  title : "Title" ,
  message : "Message" ,
  button : { label : "OK" , handler : function() { alert( "OK is clicked"); } },
  cancel : { label : "Cancel" , handler : function() { alert( "Cancel is clicked"); } },
  dismiss : function() { alert("Dismissed!"); }
} ).then(
    function(btnLabel) { alert( "open" ); },
    function(fail) { alert( JSON.stringify(fail) ); }
);

dismissAlertDialog()

Close the Alert dialog.

monaca.InAppUpdater.dismissAlertDialog(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
setTimeout( function() {
  monaca.InAppUpdater.dismissAlertDialog().then(
      function(json) { alert( "OK auto close" ); },
      function(fail) { alert( JSON.stringify(fail) ); }
  );
} , 1000 );

showProgressDialog()

Show a Progress dialog indicating the update progress.

monaca.InAppUpdater.showProgressDialog(args: JSON object): Promise

Parameter: JSON Object
Name Data Type Description
title String Title of the dialog
message String Message content
max Integer The maximum value of a counter. When downloading files, it will be a total number of files.
progress Integer A value that indicates the progress. When downloading files, it will be a total number of files downloaded.
cancel JSON Object

A cancel button in the dialog consists of 2 elements such as :

  • label: [String] The label of the cancel button
  • handler: A function to be called when the cancel button is clicked.

Example:

{
    label : "Close",
    handler : function() { alert("Close is clicked"); }
}
dismiss Callback A function to be called when a dialog is closed.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.showProgressDialog(
  { title : "Title" ,
    message : "Message" ,
    max : 100 ,
    progress : 50 ,
    cancel : { label : "Cancel" , handler : function() { log("cancel handler"); } } ,
    dismiss : function() { log("dismissed."); }
  } ).then(
  function(json) {
    alert(JSON.stringify(json));
  },
  function(fail) {
    alert( JSON.stringify(fail));
  }
);

changeProgressDialog()

Change the Progress dialog.

monaca.InAppUpdater.changeProgressDialog(args: JSON object): Promise

Parameter: JSON Object
Name Data Type Description
progress Integer A value of the progress to be changed/updated.
Return Value: Promise
  • Success callback has no argument.
  • There is no fail callback.
Example
monaca.InAppUpdater.changeProgressDialog( { progress: progress } ).then(
  function() {
    if (progress < 100) {
      setTimeout( function() { changeProgressDialog(progress+10); } , 500 );
    } else {
      monaca.InAppUpdater.dismissProgressDialog().then(
        function(json) { log("complete"); } ,
        function(error) { alert( JSON.stringify(error) ); }
      );
    }
  }
)

dismissProgressDialog()

Close a Progress dialog.

monaca.InAppUpdater.dismissProgressDialog(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object indicating the result.
  • Fail callback receives a JSON object indicating the error(s).
Example
setTimeout( function() {
  monaca.InAppUpdater.dismissProgressDialog().then(
    function(json) { alert(JSON.stringify(json)); } ,
    function(error) { alert( JSON.stringify(error) ); }
  );
} , 1000 );

networkStatus()

Check the network status (Wifi, 3G/LTE, or disconnected).

monaca.InAppUpdater.dismissAlertDialog(): Promise

Parameter
There is no argument for this method.
Return Value: Promise
  • Success callback receives a JSON object as shown below:
Name Data Type Description
network Boolean Return true if carrier network (i.e. Docomo, KDDI, …) is available.
wifi Boolean Return true if Wifi is available.
mobile Boolean Return true if a network connection (Wifi or carrier network) is available. Otherwise, return false when there is no connection available.
  • Fail callback receives a JSON object indicating the error(s).
Example
monaca.InAppUpdater.networkStatus().then(
    function(json) { alert( JSON.stringify(json) ); },
    function(fail) { alert( JSON.stringify(fail) ); }
);

terminateApp()

Terminate/Shut down the app.

Note

This method is added for compatibility with the old InAppUpdater plugin ( v2.0.4 ) for Cordova 5.

Warning

For iOS, this is equivalent to shutdown/crash so we do not recommend to use. Apple might reject your app because of this.

monaca.InAppUpdater.terminateApp()

Parameter
There is no argument for this method.
Return Value:
There is no return value.
Example
monaca.InAppUpdater.terminateApp();

autoUpdate()

Download the update files and update the app automatically.

monaca.InAppUpdater.autoUpdate(options: JSON object): Promise

Parameter: JSON Object
Name Data Type Description
connectDelay Integer A delay time in milliseconds before starting to connect to the server
dialogMessages JSON Object

A dialog to be displayed while updating the app. It has 3 variables such as :

  • confirm3G: [String] A text to be shown when the user is using carrier network instead of Wifi connection while downloading the update.
  • prepare: [JSON Object] An object with 2 string variables such as title and message which will displayed while preparing to download the updates.
  • download: [JSON Object] An object with 2 string variables such as title and message which will displayed while downloading the updates.
Example:
{
    confirm3G : 'These updates will be downloaded with your mobile data.',
    prepare : {
        title : 'Preparing to Dowload the Updates',
        message : 'Now checking the server version ...'},
    download : {
        title : 'Dowloading the Updates',
        message : 'Now downloading ...'}
}
nextTask Callback A function to be called when the update is done successfully.
failTask Callback A function to be called when the update is failed.
Return Value:
There is no return value.
Example
monaca.InAppUpdater.autoUpdate( {
  connectDelay : 0000,
  connectTimeout : 30000,
  readTimeout: 300000,
  nextTask : function(res) {
    if (res.requireRestart) {
      monaca.InAppUpdater.updateAndRestart().then(
        function() { },
        function(fail) { alert( JSON.stringify(fail) ); }
      );
    } else {
      alert("App is started!");
    }
  },
  failTask : function(res) {
    monaca.InAppUpdater.showAlertDialog(
      { title : "Error Code "+res.error.code ,
        message : res.error.message ,
        button : { label : "OK" , handler : function() { } }
      } ).then(
      function(json) {  },
      function(fail) { }
    );
  }
});

For Cordova 5.2 or Lower Projects

Supported Platforms

  • iOS 7 or later
  • Android 4.0 or later

Adding the Plugin in Monaca Cloud IDE

  1. From Monaca Cloud IDE menu, go to File ‣ Manage Cordova Plugins or Config ‣ Manage Cordova Plugins.
  2. Click Enable button of the Monaca In-App Updater (Version 2.x.x) to add it into your project.
../../../_images/188.png
  1. Next, you need to configure necessary information for this plugin. Find your newly added plugin under the Enable Plugins section. Then, hover the plugin and click Configure button.
../../../_images/257.png
  1. Choose an appropriate Update Mode and enter the Deploy URL storing the package update files (see Plugin Configuration). Then, click OK button.
../../../_images/346.png

Plugin Configuration

Update Mode

When there are available updates, the application will try to update the app according to the predefined update mode.

Mode Description
Default The application can run even the update process cannot be done.
Severe The application cannot run if the update process cannot be done. For instance, if the application has no network connectivity, the app will exit.

These settings are stored in config.xml file as shown below:

<preference name="monaca:UpdateMode" value="default"/>
<preference name="monaca:UpdateUrl" value="DEPLOY_URL"/>

Creating Update Package Files

The update package files are:

  • update.json: an update configuration file storing version of update file for each platform
  • android-vX.X.X.zip: an Android update file generated by Monaca
  • ios-vX.X.X.zip: an iOS update file generated by Monaca

Note

It’s possible to just update the app for iOS or Android depending on the update file(s) you have.

1. Creating update.json File

As mention above, the update.json file is an update configuration file to store the version information of the update files. Please create this file with the following format as an example:

{
  "ios": { "version": "2.0.0" },
  "android": { "version": "2.1.0" }
}

In this example, "ios": { "version": "2.0.0" } means that the ios-v2.0.0.zip file will be used to download as an in-app update for iOS.

2. Creating Android or iOS Update File

Each update file has a version number in its filename. This version number is based on the Android or iOS app’s version number when the update file is created.

You can update the version of the update file by the following steps:

  1. From Monaca Cloud IDE, go to Config ‣ iOS App Settings for iOS or go to Config ‣ Android App Settings for Android.
  2. Enter the version number and click Save button.
../../../_images/629.png

Android

../../../_images/722.png

iOS

Note

The Android and iOS version do not have be the same.

After you are done configuring the app’s information, you can start building the package file for each platform. Please do as follows:

  1. Go to iOS or Android Build screen.
  2. Select Build for Release ‣ Create a package for In-App Updater.
../../../_images/439.png
  1. Click Start Build. It may takes sometimes to create the package. So please wait.
  2. When the build is successfully completed, you can download the update package file.
../../../_images/533.png

Placing the Update Package Files

After you have created the package files (update.json, android-vX.X.X.zip and/or ios-vX.X.X.zip), you can start uploading them to your server. Please make sure to place all files at the same level. For example, if your Deploy URL is http://example.com/HelloWorld/, then your update files should be placed as follows:

http://example.com/HelloWorld/update.json
http://example.com/HelloWorld/ios-v2.0.0.zip
http://example.com/HelloWorld/android-v2.1.0.zip

Note

Using this plugin might cause your app to be rejected by the App Store. However, so far we haven’t had any known rejection yet.