App Updater
@objekt/capacitor-app-updater
Capacitor plugin to update the web contents of an app from a remote content server.
[Introduction] [Configuration] [Usage] [API Reference] [Contributors] [License]
Introduction
Cross platform CapacitorJS plugin to update the web contents of an app from a remote content server.
How it works
The plugin exposes a single AppUpdater.sync(checksumURL, checkDelay=3600000)
function that takes a URL to your
hosted web server. The plugin expects a checksum.json
file to be accessible on the root of the web server.
When called, the plugin performs the following steps:
- Check that the sync process has not already been run recently within a specified time delay.
- Load the
checksum.json
file from the web server. - Compare the checksum of the local device web content files with the server checksums.
- If nothing has changed, then terminate the job.
- If any checkums differ, then create a new bundle on the device.
- Download all files with differing checksums fresh from the web server.
- Copy all files with the same checksum over from the local device web content directory.
- Ensure all file have downloaded successfully.
- Modify the local the Capacitor app config to point to the new release bundle.
- Reload the app
Check Delay
As the sync task may delay your app startup time, you may not want to run it everytime the user launches your app.
Instead you can specify an optional check delay time in milliseconds as second argument to the sync
function to
skip syncing if the job ran within the set delay time already. This defaults to 60 minutes.
Running on Web vs Native
Running sync
on non-native environments such as the web is simply ignored. For the web version of your Capaitor
app, a Service Worker (see
Workbox) should instead be used to cache your web app files locally.
Installation
npm install @objekt/capacitor-app-updater
Configuration
This plugin will work without any configuration on Android and iOS in any Capacitor 3 project.
Usage
Step 1 - Basic Implementation (index.js)
Call AppUpdater.sync
in your capacitor web app root, e.g. your index.js file as follows:
import { AppUpdater } from '@objekt/capacitor-app-updater';
import { SplashScreen } from '@capacitor/splash-screen';
(async () => {
// Check for app updates - only if the app has not been launched in the last 60 minutes.
const didUpdate = await AppUpdater.sync("https://your-web-server-url", 1000*60*60);
// Stop processing if there was an update, as the updated would have triggered a page reload.
if (didUpdate) {
return;
}
// Load the app shell.
await import('./modules/AppShell.js');
// Hide the native splash screen.
await SplashScreen.hide();
})();
Step 2 - Build your web application
Follow your normal build process (e.g. webpack, rollup, etc.) to generate a distribution bundle of your app that contains all of the HTML, CSS, JS, and assets that you would publish to your app content server.
Step 3 - Create a checksum file for the build
Create a checksum.json
file in the build folder that contains a checksum for the build overall as well as each
individual file in the build. The checksums can be generated using any algorithm.
{
"id":"9d307fdcafb3f6f2fbcd47899df78652936cea00",
"timestamp":"2022-04-10T15:21:08.406Z",
"files":[
{
"path":"index.html",
"hash":"064c47308009992f133a44e368cf1dcfdaa9d85e"
},
{
"path":"app.39b812d9.js",
"hash":"1bd6e3344fbc3363b1faa00d1115378135aac5ce"
},
{
"path":"vendors.70682963.js",
"hash":"5b055ca612c8e6883decd76258261d85da3de644"
}
]
}
API Reference
Full API documentation here.
✨
Contributors This project follows the all-contributors specification. Contributions of any kind welcome! (emoji key)
jn42lm1 |
legehwahn |