Cartona Live Update CLI

A replacement for AppFlow's live update feature.

You need to be granted access to Cartona's deploy-api server (by default at deploy-api.cartona.com).

You also need to add code in your Ionic app using @capgo/capacitor-updater.

Using the CLI

Start by installing the CLI globally and access it from the command line in your project folder.

npm install -g @cartona/deploy-cli

You can also install it locally and then access the deploy command from inside package.json or using npm-exec.

npm install --save-dev @cartona/deploy-cli

In your project you must also run the following:

npm install @capgo/capacitor-updater
npx cap sync

Run deploy help to learn the available commands and parameters.

Using the credentials provided to you by the server administrator run deploy login at least once.

Whenever a live update is required for an Ionic project, just follow the following steps:

ionic build
deploy upload

Commands will prompt you to provide the required parameters. Alternatively you can pass them as arguments. For example:

deploy upload app=retailer dir=./www

Save common commands and parameters in your package.json scripts.

Server management

The update-api server has its own API but most common tasks can be performed from this CLI. For example:

    deploy list builds app=retailer
    deploy list permissions app=retailer
    deploy grant username=ahmed app=retailer can_upload=1

Run deploy help to learn the available commands and parameters.

Enabling your Ionic app

First, make sure automatic updates are disabled for @capgo/capacitor-updater since we will be handling the update from our own server. Edit your capacitor.config.ts file to include the following:

  plugins: {
    CapacitorUpdater: {
		  autoUpdate: false
	}
  }

Add code that runs immediately at startup. This can be a provider, a singleton class, or a class with static methods.

For example:

export class AppModule {

  constructor(private injector: Injector) {
    DeployUpdateService.init(injector);
  }
}

Implement functionality to choose when to update. The following class shows 2 possible ways; on startup and on state change:

import { Injector } from '@angular/core'
import { HttpClient, HttpParams } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';

import { App } from '@capacitor/app'
import { CapacitorUpdater } from '@capgo/capacitor-updater'
import type { BundleInfo } from '@capgo/capacitor-updater'
import { AlertController } from '@ionic/angular';
import { SplashScreen } from '@capacitor/splash-screen'

export class DeployUpdateService {

    // Your Application ID (you can have different ids for QA and Prod versions)
    private static appcode = 'photo-gallery';

    // To deploy to mobile devices:
    private static update_url = 'https://deploy-api.cartona.com';
    
    // To support running in an emulator against a localhost server:
    // private static update_url = 'http://10.0.2.2:8080';

    private static injector: Injector;
    private static http: HttpClient;
    private static alertCtrl: AlertController;
    private static bundle: BundleInfo | null = null;

    private static latest: any;
    private static device_id: string;

    public static init(injector: Injector) {
        this.injector = injector;
        this.http =  injector.get<HttpClient>(HttpClient);

        CapacitorUpdater.notifyAppReady();
    
        // Just check on every app startup..
        // If necessary, the app will restart..
        this.checkOnStartup();

        // Or check on every state change..
        // download latest whenever the app is opened
        // and do the update when the app is minimized
        this.checkOnStateChange();
    }

    private static async checkOnStartup() {
        const latest = await this.getLatest();
        this.latest = latest;

        let current = await CapacitorUpdater.current();
        if (current.bundle?.version == this.latest?.build) return;

        const device = await this.getDeviceId();

        if (latest && latest.id && latest.build) {
            let url = this.update_url + '/build/download';
            let params = new HttpParams();
            params = params.set('id', latest.id);
            params = params.set('device', device);
            url += '?' + params;

            let options = {
                url: url,
                version: latest.build + '',
            }

            try {
                this.latest = latest;
                this.bundle = await CapacitorUpdater.download(options);

                await this.saveEvent(this.latest);
                await CapacitorUpdater.set(this.bundle);

            } catch(err) {
                this.alert('Error in download ' + err);
            }
        } else {
            this.alert('No download possible');
        }
    }

    private static checkOnStateChange() {
            App.addListener('appStateChange', async (state: any) => {

            if (state.isActive) {
                // Do the download during user active app time to prevent failed download

                const device = await this.getDeviceId();
                const known = this.latest?.id;
                const latest = await this.getLatest();

                if (known == latest?.id) return;

                let current = await CapacitorUpdater.current();
                if (current.bundle?.version == this.latest?.build) return;

                if (latest && latest.build && latest.id && latest.id != known) {
                    let url = this.update_url + '/build/download';
                    let params = new HttpParams();
                    params = params.set('id', latest.id);
                    params = params.set('device', device);
                    url += '?' + params;
            
                    let options = {
                        url: url,
                        version: latest.build + '',
                    };

                    try {
                        this.latest = latest;
                        this.bundle = await CapacitorUpdater.download(options);
                    } catch(err) {
                        this.alert('Error in download ' + err);
                    }
                } else {
                    this.alert('No download possible');
                }
            }

            if (!state.isActive) {
                if (this.bundle && this.latest) {
                    // Do the switch when user leaves app or the app is minimized
                    SplashScreen.show()
                    
                    try {
                        await this.saveEvent(this.latest);

                        await CapacitorUpdater.set({ id: this.bundle.id });
                    }
                    catch (err) {
                        this.alert('' + err);
                        
                        SplashScreen.hide() // in case the set fail, otherwise the new app will have to hide it
                    }
                }
            }
        })
    }

    private static async getDeviceId(): Promise<string> {
        this.device_id = (await CapacitorUpdater.getDeviceId()).deviceId;
        return this.device_id;
    }

    private static async getLatest(): Promise<any> {
        const device = await this.getDeviceId();

        let url = this.update_url + '/build/latest';
        let params = new HttpParams();
        params = params.set('app', this.appcode);
        params = params.set('device', device);

        url += '?' + params;

        return firstValueFrom(this.http.get(url))
        .then((json: any) => {
            if (json && json.build) {
                return json.build;
            }
            if (json && json.builds) {
                if (Array.isArray(json.builds) && json.builds.length) {
                    return json.builds[0];
                }
            }
            return undefined;
        })
        .catch(err => {
            this.alert(err);
        })
    }

    private static async saveEvent(latest: any) {
        const device = await this.getDeviceId();

        let url = this.update_url + '/build/download/complete';
        let params = new HttpParams();
        params = params.set('id', latest.id);
        params = params.set('device', device);
        url += '?' + params;

        return firstValueFrom(this.http.get(url))
        .then((json: any) => {
            if (json) {
                return json.ok;
            } else return false;
        })
        .catch(err => {
            this.alert(err);
        })
    }

    static async alert(msg: string) {  
        this.alertCtrl = this.alertCtrl || this.injector.get<AlertController>(AlertController);

        const dlg = await this.alertCtrl.create({  
          message: msg,  
          buttons: ['OK']  
        });  
        await dlg.present();  
        const result = await dlg.onDidDismiss();  
      }  
}