@cartona/capacitor-deploy

Live updates for Ionic apps. Inspired by ideas from Microsoft's CodePush and Cap-go/capacitor-updater.

Currently supported in both Android and iOS.

Not yet tested for use in Production environments.

Install

npm install @cartona/deploy-capacitor
npx cap sync

Example

The DeployClient class allows control of every step of the update process.

You can check, download, and install updates in one step (e.g. at startup) or split it over phases (e.g. on application state change).

import { DeployClient, AppBuild, DeployConfig } from '@cartona/deploy-capacitor';
...

async checkUpdates() {

    // Prepare global configuration

    let config: DeployConfig = {
        server_url: 'https://deploy-api.cartona.space',
        appcode: '<application identifier used to upload and rollout>',
        native_build: '<native app version number can be obtained by a Capacitor plugin>'
    }

    // MUST call startup() with application start

    await DeployClient.startup(config);

    // Check if any updates are available for this app on this device
    // You may show your Splash screen if this method returns a pending build
    // Then remove the Splash screen once the install is successful

    const found = await DeployClient.checkLatest();

    if (found) {
        // If a build needs to be installed, download it
        // If this is not the first update, a delta build will be fetched
        // You should call this on startup or only if the app status is active

        const local = await DeployClient.download(found);

        if (local) {
            // If the download is successful, install the bundle
            // This automatically restarts the web view
            // You may call this on startup or when the app status becomes inactive

            const ok = await DeployClient.install(local);

            if (ok) {
                console.log('Installed update!! ');
            } else {
                console.log('Failed to install update ');
            }
        }
    }
}

API

• startup(...)
• getDeployConfig()
• checkLatest()
• download(...)
• install(...)
• reload()
• confirmInstall(...)
• rollback(...)
• Interfaces

startup(...)

startup(config: DeployConfig) => Promise<void>

Initialize the client and load the latest installed build.

This MUST be called IMMEDIATELY on application startup.

| Param | Type | Description | | ------------ | ----------------------------------------------------- | ------------------------------- | | config | DeployConfig | the global configuration to use |

getDeployConfig()

getDeployConfig() => Promise<DeployConfig>

Fetch the current configuration of DeployClient

including the read-only device_id and current_build values

Returns: Promise<DeployConfig>

checkLatest()

checkLatest() => Promise<AppBuild | null>

Request the latest build available for download, if any.

Returns: Promise<AppBuild | null>

download(...)

download(latest: AppBuild) => Promise<AppBuild>

Download a build from the deploy-api server.

| Param | Type | Description | | ------------ | --------------------------------------------- | --------------------- | | latest | AppBuild | the build to download |

Returns: Promise<AppBuild>

install(...)

install(latest: AppBuild) => Promise<DeployResult>

Install a downloaded build and apply immediately.

This forces an immediate reload of the web view.

| Param | Type | Description | | ------------ | --------------------------------------------- | -------------------- | | latest | AppBuild | the build to install |

Returns: Promise<DeployResult>

reload()

reload() => Promise<DeployResult>

Reload the web view using the latest installed bundle.

You normally don't call this function. This is automatically called after an install.

Returns: Promise<DeployResult>

confirmInstall(...)

confirmInstall(latest: AppBuild) => Promise<DeployResult>

Register the current build on the deploy-api server.

You normally don't call this function. This is automatically called after a successful reload.

| Param | Type | Description | | ------------ | --------------------------------------------- | -------------------- | | latest | AppBuild | the build to confirm |

Returns: Promise<DeployResult>

rollback(...)

rollback(latest: AppBuild) => Promise<DeployResult>

Return to the prior build (i.e. UNDO an install).

You normally don't call this function. This is automatically called after a failed reload.

| Param | Type | Description | | ------------ | --------------------------------------------- | ----------------- | | latest | AppBuild | the build to undo |

Returns: Promise<DeployResult>

Interfaces

DeployConfig

Global configuration for all methods.

This MUST be provided at the first method call.

| Prop | Type | Description | | ------------------- | ------------------- | ------------------------------------------------------------------------ | | server_url | string | Base url for Cartona deploy-api server <protocol>://<domain> | | appcode | string | Application identifier (used to upload and rollout builds) | | username | string | Optional user name | | device_id | string | Device identifier (set automatically) | | current_build | number | Installed build number (set automatically) | | native_build | string | Native app version number (set manually or by using Capacitor plugin) |

AppBuild

Application version (Build) metadata.

This is fetched whenever a new build is available for download.

| Prop | Type | Description | | ------------------ | ------------------- | ---------------------------------------------------------- | | id | string | Unique build identifier | | appcode | string | Application identifier (used to upload and rollout builds) | | build | number | Build number | | download_url | string | Url used to download the build bundle | | local_path | string | Local path used to save the build bundle |

DeployResult

Result of plugin calls

| Prop | Type | Description | | ----------- | -------------------- | ----------------------------------------------------------- | | ok | boolean | Holds true if the operation was successful, otherwise false | | error | string | Optional error message if the operation was not successful |