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:

1. Check that the sync process has not already been run recently within a specified time delay.
2. Load the checksum.json file from the web server.
3. Compare the checksum of the local device web content files with the server checksums.
4. If nothing has changed, then terminate the job.
5. If any checkums differ, then create a new bundle on the device.
6. Download all files with differing checksums fresh from the web server.
7. Copy all files with the same checksum over from the local device web content directory.
8. Ensure all file have downloaded successfully.
9. Modify the local the Capacitor app config to point to the new release bundle.
10. 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)

License

MIT