Monaca In-App Updater

PreviousMonaca HTML5 Resource Encryption NextMonaca Secure Storage

Last updated 9 months ago

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.

In order to use this plugin, you are required to subscribe to a valid plan. Please refer to Monaca Subscription Plans.

This plugin is not available for custom build debuggers. If you want to check the operation, you need to debug build the app.

Supported Platforms

Cordova 7.1 or higher
iOS 9 or later
- For WKWebView version (5.0.5 or later): iOS 11 or later
- CustomScheme supporting version（6.1.0 or later）: iOS 11 or later
Android 4.1 or later

If you are using WKWebView, you need to use version 5.0.5 or later.

Adding the Plugin in Monaca Cloud IDE

From Monaca Cloud IDE menu, go to Configure → Cordova Plugin Settings.
Under Available Plugins section, hover over the the InAppUpdater plugin and click Enable button.

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

4. Input the CheckUpdate URL and Download URL appropriately. Then, click OK button.

Create an HTML5 asset for update

Select the following from Monaca Cloud IDE and click the Start Build button.

Build → Build App for Android → Build for Release → Create a package for In-App Updater
Build → Build App for iOS → Build for Release → Create a package for In-App Updater

Usage

This plugin updates the HTML5 asset for the version of the target application. When updating the HTML5 asset, set a new update number in the update file on the web server side.

For the update file on the Web server side, see CheckUpdate URL.

Plugin Configuration

To use this plugin, you need two Web APIs (URL), CheckUpdate URL and Download URL.

CheckUpdate URL

Specifies the URL of the Web API that provides update file information. Update file information is created in JSON format as follows. It can be obtained by the updateInfo parameter of a JSON object returned by the promise of getServerVersion() method.

Request Parameters

{
  "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.
      }
    }
  },
    "android": {
    "2.1.0": {　// app version
      "1": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/1/android-v2.1.0.zip" // This parameter is optional.
      },
      "2": { // update number
        "date": 20170113,
        "url": "https://hogehoge.com/app/2/android-v2.1.0.zip" // This parameter is optional.
      }
    },
    "2.2.0": {　// app version
      "1": { // update number
        "date": 20170210,
        "url": "https://hogehoge.com/app/1/android-v2.2.0.zip" // This parameter is optional.
      }
    }
  }
}

Download URL

Specify the URL of the HTML5 asset file (zip format) for update .

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

API Reference

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

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

Get the currect version of the app.

Download the update files.

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

Get the current status of the plugin.

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

Close the Alert dialog.

Show a Progress dialog indicating the update progress.

Change the Progress dialog.

Close a Progress dialog.

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

Terminate/Shut down the app.

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)

Property

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:
Property
Data Type
Description
needsUpdate
Boolean
Indicates if the current app version needs to be updated.
updatable
Boolean
Indicates if there are update files applicable to the current app version.
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

None

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 current version of the app.

monaca.InAppUpdater.getLocalVersion(): Promise

Parameter

None

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

version

String

The target app version

updateNumber

Integer

The update number

bufferSize

Integer

(Android only) Buffer size in bytes. The default value is 8192.

url

String

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, updateNumber : 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

None

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

None

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

None

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 cancel button
handler: A function to be called when the cancel button is clicked.

Example: {

label : "OK",

handler : function() { alert("OK is clicked"); }

}

cancel

JSON Object

A 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() { console.log("OK is clicked"); } },
    cancel : { label : "Cancel" , handler : function() { console.log("Cancel is clicked"); } },
    dismiss : function() { console.log("Dismissed!"); }
} ).then(
    function(btnLabel) { console.log("open"); },
    function(fail) { console.log(JSON.stringify(fail)); }
);

dismissAlertDialog()

Close the Alert dialog.

monaca.InAppUpdater.dismissAlertDialog(): Promise

Parameter

None

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) { console.log("OK auto close"); },
        function(fail) { console.log(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() { console.log("cancel handler"); } } ,
    dismiss : function() { console.log("dismissed."); }
    } ).then(
    function(json) {
      console.log(JSON.stringify(json));
    },
    function(fail) {
      console.log(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) { console.log("complete"); } ,
        function(error) { console.log(JSON.stringify(error)); }
        );
    }
    }
)

dismissProgressDialog()

Close a Progress dialog.

monaca.InAppUpdater.dismissProgressDialog(): Promise

Parameter

None

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) { console.log(JSON.stringify(json)); } ,
    function(error) { console.log(JSON.stringify(error)); }
    );
} , 1000 );

networkStatus()

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

monaca.InAppUpdater.networkStatus(): Promise

Parameter

None

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.

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

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

None

Return Value

None

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

None

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) { }
    );
    }
});

Notes on Android 9+

In principle, http protocol communication is prohibited on Android 9 and later. Therefore, the update file needs to be modified to be obtained by https protocol.

If http protocol communication is required for the operation test, you need to add the usesCleartextTraffic by adding the andorid namespace to the widget tag of config.xml as shown below.

<widget xmlns:android="http://schemas.android.com/apk/res/android">

<platform name="android">
  <edit-config file="AndroidManifest.xml" target="/manifest/application" mode="merge">
    <application android:usesCleartextTraffic="true" />
  </edit-config>
</platform>

CustomScheme configuration (Cordova 10 or later + this plugin 6.1.0 or later, iOS only)

In iOS, we can set the scheme and hostname for this plugin. (Same as HTML5 Resource Encryption plugin)

The default scheme and hostname of Cordova 10 are as follows.

<preference name="scheme" value="monaca-app"/>
<preference name="hostname" value="localhost"/>

Please remove this default setting. If you specify this, you will get a build error.

You can then set the scheme and hostname in config.xml as follows.

<preference name="monaca:scheme" value="monacax-app"/>
<preference name="monaca:hostname" value="monacax.io"/>

In this example, the scheme is "monacax-app" and the hostname is "monacax.io". The characters that can be used in the scheme are as shown in RFC 2396 Appendix A

 scheme        = alpha *( alpha | digit | "+" | "-" | "." )

Also, if you omit monaca:scheme and moanca:hostname, they become monaca-plugin and monaca.plugin respectively.

Release Note

Version

Changes

7.1.1

Support cordova-ios 7.1.0

6.2.3

Automatic lowercase recognition of uppercase schemes and host names

6.2.2

Fixed a bug when retrieving json files from external sites

6.2.1

Progress bar style modification

6.2.0

cSupport cordova-android 10 series or later (cordova-android 9 series is no longer supported)

6.1.0

Support CustomScheme

6.0.0

Support Cordova10 (Cordova9 series is no longer supported)

Privacy Manifest

The privacy manifest required by this plugin is as follows. (cordova-ios 7.1.0 or greater)

<platform name="ios">
  <privacy-manifest>
    <key>NSPrivacyTracking</key>
    <false/>
    <key>NSPrivacyTrackingDomains</key>
    <array/>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
    <dict>
      <key>NSPrivacyAccessedAPIType</key>
      <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
      <key>NSPrivacyAccessedAPITypeReasons</key>
      <array>
      <string>CA92.1</string>
      </array>
    </dict>
    <dict>
      <key>NSPrivacyAccessedAPIType</key>
      <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
      <key>NSPrivacyAccessedAPITypeReasons</key>
      <array>
      <string>0A2A.1</string>
      </array>
    </dict>
    </array>
    <key>NSPrivacyCollectedDataTypes</key>
    <array/>
  </privacy-manifest>
</platform>

For more information on how to write a manifesto, see https://en.docs.monaca.io/release_notes/privacy-manifest-requirement-for-ios-apps#setting-up-the-privacy-manifest .