Démarrer avec Cordova Updater

Ce guide vous accompagne pour ajouter @capgo/cordova-updater à une application Cordova afin de recevoir des Capgo live updates sur iOS et Android.

Attention

Ne pas utiliser cordova-plugin-ionic-webview avec ce plugin. L'Ionic WebView contourne les gestionnaires de schémas de Cordova, les bundles téléchargés ne pourront donc pas se charger.

Prerequisites

• Cordova CLI 12+
• Cordova Android 13+ et/ou Cordova iOS 7+
• Un compte Capgo (capgo.app/register)

Installation

1. Installez le plugin via npm en passant votre ID d'application Capgo :

   cordova plugin add @capgo/cordova-updater --variable APP_ID=YOUR_CAPGO_APP_ID

2. Optionnel : remplacez les valeurs par défaut lors de l'installation (mêmes variables que l'updater Capacitor) :

   cordova plugin add @capgo/cordova-updater \
     --variable APP_ID=YOUR_CAPGO_APP_ID \
     --variable DEFAULT_CHANNEL=production \
     --variable UPDATE_URL=https://plugin.capgo.app/updates \
     --variable AUTO_UPDATE=atBackground

3. Préparez les projets natifs après avoir modifié les variables du plugin :

   cordova prepare android ios

Démarrage rapide

document.addEventListener('deviceready', async () => {
  await cordova.plugins.Updater.notifyAppReady();
});

Erreurs courantes

• N'utilisez pas cordova-plugin-ionic-webview avec ce plugin.
• Appelez notifyAppReady() dès que votre bundle est chargé — avant que des tâches UI lourdes ne retardent la fenêtre de rollback.
• Maintenez les paramètres du schéma Cordova corrects.

Usage du JavaScript

Après deviceready, le plugin est disponible via cordova.plugins.Updater:

document.addEventListener('deviceready', async () => {
  const { Updater } = cordova.plugins;

  await Updater.notifyAppReady();

  const latest = await Updater.getLatest();
  if (latest.url && !latest.error) {
    const bundle = await Updater.download({
      url: latest.url,
      version: latest.version,
      checksum: latest.checksum,
    });

    await Updater.next({ id: bundle.id });
  }
});

Les types TypeScript sont inclus dans le package npm :

import type { UpdaterPlugin } from '@capgo/cordova-updater';

declare const cordova: { plugins: { Updater: UpdaterPlugin } };

Notes sur les plateformes

Android

• Nécessite Cordova Android 13+ pour que la WebView soit servie via le https://localhost/ scheme.
• Le plugin enregistre un CordovaPluginPathHandler pour servir les assets du bundle téléchargé.

iOS

• Nécessite Cordova iOS 7+ avec le app://localhost/ scheme.
• Le plugin implémente CDVPluginSchemeHandler pour intercepter les requêtes de bundle.

Envoyez votre premier bundle

Compilez vos assets web, puis effectuez l'upload avec le Capgo CLI (même workflow que Capacitor) :

bun run build
npx @capgo/cli@latest bundle upload --channel=production

Étapes suivantes

• Comparez les paramètres avec la configuration de l'updater Capacitor — la plupart des options correspondent à des plugin.xml variables.
• Lecture Compatibilité Live update avant de déployer les changements du plugin natif.
• Migrer vers Capacitor plus tard ? Gardez le même Capgo app ID et les mêmes canaux ; seul le package du plugin client change.