# 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. {% hint style="info" %} In order to use this plugin, you are required to subscribe to a valid plan. Please refer to [Monaca Subscription Plans](https://monaca.mobi/en/pricing). {% endhint %} {% hint style="info" %} This plugin is not available for custom build debuggers.\ If you want to check the operation, you need to debug build the app. {% endhint %} ## 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 {% hint style="info" %} If you are using WKWebView, you need to use version 5.0.5 or later. {% endhint %} ## Adding the Plugin in Monaca Cloud IDE 1. From Monaca Cloud IDE menu, go to `Configure → Cordova Plugin Settings`. 2. Under *Available Plugins* section, hover over the the `InAppUpdater` plugin and click `Enable` button. ![](/files/-MfbwkCf8erCi3sfJj0v) 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. ![](/files/-MfbwntJn1VjMjDb9i1H) 4\. Input the [CheckUpdate URL](/reference/power_plugins/in-app_updater.md#checkupdate-url) and [Download URL](/reference/power_plugins/in-app_updater.md#download-url) appropriately. Then, click `OK` button. ![](/files/-MfbwrPrzEZV9Dw104w1) ## 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](/reference/power_plugins/in-app_updater.md#checkupdate-url). ### Plugin Configuration To use this plugin, you need two Web APIs (URL), [CheckUpdate URL](/reference/power_plugins/in-app_updater.md#checkupdate-url) and [Download URL](/reference/power_plugins/in-app_updater.md#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()](/reference/power_plugins/in-app_updater.md#getserverversion) method. **Request Parameters** ```javascript { "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 . {% hint style="info" %} You can omit this preference if you set a download URL with [download](/reference/power_plugins/in-app_updater.md#download). {% endhint %} ## API Reference The easiest way to use this plugin is to only use [autoUpdate()](/reference/power_plugins/in-app_updater.md#autoupdate) which will download the update files (as configure in [Plugin Configuration](/reference/power_plugins/in-app_updater.md#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()](/reference/power_plugins/in-app_updater.md#getserverversion), [download()](/reference/power_plugins/in-app_updater.md#download), [updateAndRestart()](/reference/power_plugins/in-app_updater.md#updateandrestart) and so on. Here is the list of all available methods for this plugin: | Methods | Description | | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [getServerVersion()](/reference/power_plugins/in-app_updater.md#getserverversion) | Get the information of files to be updated from the server. | | [forceStopGetServerVersion()](/reference/power_plugins/in-app_updater.md#forcestopgetserverversion) | Force [getServerVersion()](/reference/power_plugins/in-app_updater.md#getserverversion) to stop. | | [getLocalVersion()](/reference/power_plugins/in-app_updater.md#getlocalversion) | Get the currect version of the app. | | [download()](/reference/power_plugins/in-app_updater.md#download) | Download the update files. | | [forceStopDownload()](/reference/power_plugins/in-app_updater.md#forcestopdownload) | Force [download()](/reference/power_plugins/in-app_updater.md#download) to stop. | | [updateAndRestart()](/reference/power_plugins/in-app_updater.md#updateandrestart) | Deploy and mount the downloaded update files, and then restart the app. | | [status()](/reference/power_plugins/in-app_updater.md#status) | Get the current status of the plugin. | | [showAlertDialog()](/reference/power_plugins/in-app_updater.md#showalertdialog) | Show a dialog with a title and a message. Only one dialog is shown at a time. | | [dismissAlertDialog()](/reference/power_plugins/in-app_updater.md#dismissalertdialog) | Close the Alert dialog. | | [showProgressDialog()](/reference/power_plugins/in-app_updater.md#showprogressdialog) | Show a Progress dialog indicating the update progress. | | [changeProgressDialog()](/reference/power_plugins/in-app_updater.md#changeprogressdialog) | Change the Progress dialog. | | [dismissProgressDialog()](/reference/power_plugins/in-app_updater.md#dismissprogressdialog) | Close a Progress dialog. | | [networkStatus()](/reference/power_plugins/in-app_updater.md#networkstatus) | Check the network status (Wifi, 3G/LTE, or disconnected). | | [terminateApp()](/reference/power_plugins/in-app_updater.md#terminateapp) | Terminate/Shut down the app. | | [autoUpdate()](/reference/power_plugins/in-app_updater.md#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. ```javascript 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": "" // This parameter is optional.

}

}

}

}

Then, the value of updateInfo will be:

updateInfo = {

"date": 20170113,

"url": ""

}

| * Fail callback receives a JSON object indicating the error(s). **Example** ```javascript 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. ```javascript 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** ```javascript monaca.InAppUpdater.forceStopGetServerVersion().then( function(str) { alert("stop success"); } , function(fail) { alert( JSON.stringify(fail) ); } ); ``` ### getLocalVersion() Get the current version of the app. ```javascript 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** ```javascript monaca.InAppUpdater.getLocalVersion().then( function(json) { alert( JSON.stringify(json) ); } , function(fail) { alert( JSON.stringify(fail) ); } ); ``` ### download() Download the update files. ```javascript 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 | The URL where you download the ZIP file from. If this value is not existed, the value of [Download URL](/reference/power_plugins/in-app_updater.md#download-url) (`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** ```javascript 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. ```javascript 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** ```javascript 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. ```javascript 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** ```javascript 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. ```javascript 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** ```javascript 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. ```javascript 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:

Example:
{

label : "OK",

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

}

| | `cancel` | JSON Object |

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

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** ```javascript 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. ```javascript 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** ```javascript 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. ```javascript 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 :

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** ```javascript 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. ```javascript 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** ```javascript 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. ```javascript 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** ```javascript 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). ```javascript 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** ```javascript monaca.InAppUpdater.networkStatus().then( function(json) { alert( JSON.stringify(json) ); }, function(fail) { alert( JSON.stringify(fail) ); } ); ``` ### terminateApp() Terminate/Shut down the app. {% hint style="info" %} This method is added for compatibility with the old `InAppUpdater` plugin ( v2.0.4 ) for Cordova 5. {% endhint %} {% hint style="danger" %} For iOS, this is equivalent to shutdown/crash so we do not recommend to use. Apple might reject your app because of this. {% endhint %} ```javascript monaca.InAppUpdater.terminateApp() ``` **Parameter** * None **Return Value** * None **Example** ```javascript monaca.InAppUpdater.terminateApp(); ``` ### autoUpdate() Download the update files and update the app automatically. ```javascript 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:

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** ```javascript 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. ```markup ``` ## 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. ```markup ``` 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. ```markup ``` 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](https://datatracker.ietf.org/doc/html/rfc2396#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.2 | Support cordova-android 13 | | 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) ``` NSPrivacyTracking NSPrivacyTrackingDomains NSPrivacyAccessedAPITypes NSPrivacyAccessedAPIType NSPrivacyAccessedAPICategoryUserDefaults NSPrivacyAccessedAPITypeReasons CA92.1 NSPrivacyAccessedAPIType NSPrivacyAccessedAPICategoryFileTimestamp NSPrivacyAccessedAPITypeReasons 0A2A.1 NSPrivacyCollectedDataTypes ``` 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](/release_notes/privacy-manifest-requirement-for-ios-apps.md) . --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://en.docs.monaca.io/reference/power_plugins/in-app_updater.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.