AppUpdate

The AppUpdate plugin is used to enable the contents under the www folder (HTML, JavaScript, CSS, images, etc.) of a deployed Kapsel app to be updated. As an example, a new project named AppUpdateDemo will be created and used to demonstrate how to update a deployed app. A Kapsel app with the AppUpdate plugin installed will check with the SMP 3.0 server on startup to see if there is a newer version of the Kapsel app available. The revision number of the Kapsel app is automatically incremented with each deployment to the SMP 3.0 server. If the revision on the server is higher than the revision in the config.xml on the device or simulator, then a notification is shown asking the user if they wish to accept the update.

For additional details see the JavaScript file in a project that includes this plugin at

project_name\plugins\com.sap.mp.cordova.plugins.appupdate\www\appupdate.js

or the JS Documentation at Kapsel AppUpdate API Reference.

The following steps will demonstrate this plugin.

Follow the steps shown in Configuring a Kapsel App in the Management Cockpit to create an Application with the application ID of
```
com.mycompany.appupdate
```
This app does not use an OData endpoint so that can be set to a dummy URL such as
```
http://www.mycompany.com
```

Create a new project named AppUpdateDemo and add Android or iOS or both.

cordova -d create C:\Kapsel_Projects\AppUpdateDemo com.mycompany.appupdate AppUpdateDemo
cd AppUpdateDemo
cordova -d platform add android

cordova -d create ~/Documents/Kapsel_Projects/AppUpdateDemo com.mycompany.appupdate AppUpdateDemo
cd ~/Documents/Kapsel_Projects/AppUpdateDemo
cordova -d platform add ios

Add the AppUpdate plugin and optionally the logger plugin if you wish to view the messages logged by the AppUpdate plugin. The log level is set to debug if sap.Logger is detected on line 12 of index.html.

cordova -d plugin add C:\SAP\MobileSDK3\KapselSDK\plugins\appupdate
cordova -d plugin add C:\SAP\MobileSDK3\KapselSDK\plugins\logger

cordova -d plugin add ~/SAP/MobileSDK3/KapselSDK/plugins/appupdate
cordova -d plugin add ~/SAP/MobileSDK3/KapselSDK/plugins/logger

Replace the contents of C:\Kapsel_Projects\AppUpdateDemo\www\index.html with index.html.zip.

Note the application ID is specified in index.html as
```
var appId = "com.mycompany.appupdate";
```
The user and password values do not matter in this example as an OData endpoint is not being used.
Optionally modify the AppUpdateDemo\www\config.xml to add
```
<preference name="hybridapprevision" value="1" /><preference name="sap-development-version" value="1.2.3" />
```
Due to a long delay on Android while assets are being copied during the first app update, it is recommended to either not specify hybridapprevision or use value="0". When hybridapprevision is not present or set to 0, during the first client update, the client will request the server to send the complete contents of the www folder rather than just the files that changed between the revision that is reported on the client and the version on the server.
Copy the contents of the www folder to the platform specific www folder of the project using prepare.
```
cordova -d prepare
```
Optionally modify the description in the platform specific config.xml. Note, this is done after the prepare to the platform specific config.xml due to a cordova bug.
Deploy the Kapsel app to the device or simulator using the Android IDE or Xcode.
In the All Output tab in Xcode or in Eclipse under the LogCat view, the debug output from the AppUpdate plugin can be seen. Note that the LogCat view provides a feature to filter messages. The filter shown below is based on the Tag SMP_APP_UPDATE.

Notice above that when the app starts, the AppUpdate plugin checks with the SMP server to see if there is a newer version of the app. The current version of the app is appRevision 1. We have not yet deployed a version of the app to the server so a 404 error is returned.
The Kapsel command line interface (CLI) provides a way to generate a zip file that contains the HTML files that make up the app. This zip file can then either be uploaded to the SMP 3.0 server using the Management Cockpit or it can be uploaded using the Kapsel command line interface. Open a command prompt or shell to the folder
```
C:\SAP\MobileSDK3\KapselSDK\cli

 ~/SAP/MobileSDK3/KapselSDK/cli
```
Run
```
npm install -g
```
On a Mac it may be necessary to run
```
sudo npm -g install
```
See the section Installing Apache Cordova with Node.js for additional details on setting proxy settings if your company uses a proxy server.

Change directories to the directory containing the project and run the below commands to generate a zip file containing the HTML files that make up the application and then upload the zip file to the SMP 3.0 server.
```
kapsel package
kapsel deploy com.mycompany.appupdate localhost:8083 smpAdmin s3pAdmin
```
The package command can optionally take a platform such as android or iOS. The parameters to the deploy command are the SMP 3.0 server host name, the app ID, the user id, and password for the SMP 3.0 server. After running this command the Management Cockpit will show that revision 1 has been uploaded to the server.

Note, to get the device specific config.xml file needs to be modified rather than the shared one under the www folder.

At this point the version of the application on the device is the same as the version on the server.
Update C:\Kapsel_Projects\AppUpdateDemo\www\index.html and change the body's background-color to some other color such as silver.
```
<style type="text/css">  body {    background-color: silver;  }</style>
```
Copy the contents of the www folder to the platform specific www folder of the project using prepare.
```
cordova -d prepare android

cordova -d prepare ios
```
Deploy a new version of app to the SMP 3.0 server.
```
kapsel package
kapsel deploy com.mycompany.appupdate localhost:8083 smpAdmin s3pAdmin
```
Close and reopen the AppUpdateDemo app.

The debug output from the AppUpdate plugin shows that the client has revision 1 and the server has revision 2. It also lists the changed files which in this case is index.html.
The www folder on the device or simulator is read only and cannot be updated directly, so the first app update causes the entire contents of the www folder to be copied to a new location causing the size of the deployed application to increase.
Note, occasionally the unlock screen fails to display when using the Android 4.4 emulator with AppUpdate. This has been reported as issue 525419
Note, rather than having the end user ok the update, the update can happen without the user being asked to ok it by overriding the sap.AppUpdate.onupdateready event.
```
// Override default handler
sap.AppUpdate.onupdateready = function(e) {   // No notification just reload   console.log("Apply update");   sap.AppUpdate.reloadApp();
}
```
See comments in appupdate.js for further details.
Note, it is important to test the changes before publishing them to the server. If an error is introduced, it could cause the application to break and potentially prevent future updates from being downloaded. You can also validate your JavaScript with tools like JSLint, or JSHint. CSS can be validated with CSS Lint. If you encounter a problem after an update has occurred and you are using an iOS simulator, the contents of the update can be viewed at the following location.
```
/Users/user_name/Library/Application Support/iPhone Simulator/6.1/Applications/xxxx-xxx-xxx-xxx-xxxxx/Documents/SMP/appupdate/app/www
```
One technique to aid with this problem is to open an error page that can check for new updates if an error is detected.
Replace the contents of C:\Kapsel_Projects\AppUpdateDemo\www\index.html with index2.html.zip and add error.html.zip.
Line 12 can be uncommented which makes a call to a non existent JavaScript method. The app that now has an error in it can be packaged and deployed to the SMP 3.0 server. When the app is reopened, the newer version is uploaded and the error handler detects an error and redirects to the error page.

Correct the error, package and deploy the app.
Now press check for updates and notice that app has recovered from the error.