Guide d'onboarding CLI

Aperçu rapide

Capgo CLI propose un onboarding interactif qui configure les live updates de votre application Capacitor. Vous allez :

1. ✅ Enregistrer votre application dans Capgo
2. 🔌 Installer et configurer le plugin updater
3. 🚀 Déployer votre premier live update
4. 📱 Tester la mise à jour sur votre appareil

Temps estimé : 10-20 minutes (variable selon votre connexion internet et le temps de build)

Astuce

L'onboarding est entièrement reprenable — quittez à tout moment et reprenez plus tard là où vous vous êtes arrêté.

Démarrer l'onboarding

Exécutez la commande d'onboarding avec votre clé API :

npx @capgo/cli@latest init [APIKEY]

Vous verrez le message de bienvenue :

Capgo onboarding 🛫

Ce qui se passe pendant l'onboarding

CLI vous guidera à travers 13 étapes interactives :

Phase de configuration (étapes 1 à 6) :

• Vérifiez votre environnement de développement (Xcode/Android Studio)
• Ajoutez votre app à Capgo et créez un canal de production
• Installez le @capgo/capacitor-updater plugin
• Injectez le code requis dans votre app
• Activez éventuellement le chiffrement de bout en bout
• Choisissez une plateforme pour les tests (iOS ou Android)

Phase de test (étapes 7 à 12) :

• Compilez votre app et lancez-la sur un appareil ou un simulateur
• Effectuez un changement code visible (automatique ou manuel)
• Envoyez le bundle mis à jour vers Capgo
• Voir live update apparaître sur votre appareil en temps réel

Terminé (étape 13) :

• Votre application est prête pour les live updates ! 🎉

Le processus d'onboarding en 13 étapes

Étape 1 : Vérifier les prérequis

CLI vérifie votre environnement de développement pour vous assurer que les outils nécessaires sont installés.

Éléments vérifiés :

• Xcode (macOS uniquement) - pour le développement iOS
• SDK Android - pour le développement Android

Résultats possibles :

✅ Les deux environnements détectés :

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ Aucun environnement détecté :

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

Questions qui peuvent vous être posées :

Attention

Si aucun environnement de développement n'est détecté, on vous demandera si vous souhaitez continuer. Il est recommandé d'installer au moins une plateforme avant de poursuivre.

Étape 2 : ajoutez votre application

CLI vous connectera à Capgo et ajoutera votre application à votre compte.

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

Si l'ID de votre application est déjà utilisé :

CLI proposera des alternatives :

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

Vous pouvez choisir une suggestion ou saisir un ID d'application personnalisé.

Remarque

Les ID d'application doivent suivre la notation de domaine inversée (ex : com.example.myapp)

Étape 3 : Créer le canal de production

Les canaux vous permettent de gérer différents flux de mises à jour pour votre application.

❓ Create default channel production for {appId} in Capgo?

Astuce

Ne vous inquiétez pas ! Ceci est uniquement pour les tests locaux durant l'onboarding. Créer un canal « production » ne signifie pas que vos mises à jour seront déployées immédiatement auprès de vos clients. Vous gardez le contrôle total sur le moment où les mises à jour sont déployées. Sélectionnez Oui sauf si vous avez des besoins spécifiques pour vos canaux.

Si vous sélectionnez Oui :

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

Un canal de production sera créé et défini par défaut. C'est l'option recommandée pour la plupart des utilisateurs.

Si vous sélectionnez Non :

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

Vous devrez créer et configurer les canaux manuellement plus tard. Sinon, vous pouvez :

• Définir le canal dans votre capacitor.config.ts fichier
• Utilisez le JavaScript setChannel() méthode JavaScript pour définir le canal dynamiquement
• Configurer les canaux plus tard depuis la console web Capgo

Étape 4 : Installer le plugin Updater

Le CLI installera le @capgo/capacitor-updater plugin compatible avec votre version Capacitor.

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

Compatibilité des versions :

• Capacitor 5 : installations @capgo/capacitor-updater v5
• Capacitor 6 : installations @capgo/capacitor-updater v6
• Capacitor 7 : installations @capgo/capacitor-updater v7
• Capacitor 8+ : dernière version installée

Attention

Capgo ne prend en charge que Capacitor v5 et versions supérieures. Si vous utilisez une version antérieure, vous devez d’abord effectuer une mise à niveau.

Option de mises à jour instantanées :

Après l’installation, on vous demandera :

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

Astuce

Qu’est-ce que les mises à jour instantanées ? Avec les mises à jour instantanées activées, votre application applique les mises à jour immédiatement lorsqu’elle est mise en arrière-plan puis rouverte. Cela fonctionne sans accroc car Capgo peut distribuer des mises à jour dans le monde entier en moins de 300 ms. Sans cette option (mode standard), les mises à jour sont téléchargées en arrière-plan et appliquées au redémarrage suivant de l’application. Les mises à jour instantanées sont idéales pour itérer plus rapidement pendant le développement et corriger des bugs critiques en production.

Si vous sélectionnez Oui :

• Les mises à jour seront configurées pour s’appliquer immédiatement lorsque l’app passe en arrière-plan puis est rouverte
• autoUpdate: 'always' et autoSplashscreen: true sera ajouté à votre configuration
• @capacitor/splash-screen sera installé s’il est absent, avec launchAutoHide: false
• Votre capacitor.config.ts sera mis à jour automatiquement
• Mises à jour delta restent activés. Application immédiate (always, atInstall, onLaunch) doit continuer à utiliser npx @capgo/cli@latest bundle upload --delta afin que seuls les fichiers modifiés soient téléchargés et que l’utilisateur n’attende pas un zip complet

Si vous sélectionnez Non :

• Les mises à jour utiliseront le comportement standard (téléchargement en arrière-plan, application au redémarrage suivant)
• Vous pouvez toujours activer les mises à jour instantanées plus tard en modifiant votre capacitor.config.ts

Étape 5 : Ajouter l'intégration Code

Le CLI injecte automatiquement le code requis dans votre fichier d’application principal.

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

Ce qui est ajouté :

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Détection du type de projet :

• Nuxt.js: crée plugins/capacitorUpdater.client.ts
• Autres frameworks: S'ajoute à votre fichier d'entrée principal

Astuce

Si l'auto-injection échoue, vous pouvez ajouter le code manuellement à votre fichier d'application principal :

Pour Nuxt.js : Créer plugins/capacitorUpdater.client.ts:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

Pour les autres frameworks : Ajoutez-l’à votre fichier d'entrée principal (ex : main.ts, index.js, App.tsx):

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Placez ce code après vos imports et avant l'initialisation de votre app. Pour plus de détails, consultez le Guide d'ajout d'app.

Étape 6 : Configurer le chiffrement (optionnel)

Le chiffrement de bout en bout ajoute une couche de sécurité supplémentaire à vos mises à jour.

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

Remarque

Le chiffrement n’est disponible que pour Capacitor v6 et versions ultérieures.

Si vous activez le chiffrement, CLI :

1. Génère des clés de chiffrement
2. Propose de synchroniser votre configuration Capacitor

Étape 7 : Sélectionner la plateforme

Choisissez la plateforme à tester pendant l’onboarding.

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

Astuce

Cela n’affecte que le processus d’onboarding. Votre application finale prendra en charge toutes les plateformes.

Étape 8 : Compiler votre projet

CLI va compiler votre application et la synchroniser avec Capacitor.

❓ Automatic build {appId} with "npm run build"?

Ce qui se passe :

1. Détecte le type de votre projet
2. Exécute votre script de build
3. Exécute des npx cap sync {platform}

Si le script de build est manquant :

On vous demandera si vous voulez ignorer le build ou ajouter un script de build à votre package.json.

Étape 9 : Lancer sur l'appareil

Testez la version initiale de votre app sur un appareil ou un simulateur.

❓ Run {appId} on {PLATFORM} device now to test the initial version?

Si vous sélectionnez Oui:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

Étape 10 : Faire une modification de test

Il est maintenant temps de tester le système de mise à jour de Capgo en apportant un changement visible.

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

Mode automatique : Le CLI modifie automatiquement vos fichiers pour ajouter un bandeau de test visible ou une modification.

Mode manuel : You make your own changes (e.g., change text, colors, or add elements).

Gestion des versions :

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

Compiler avec les modifications :

❓ Build {appId} with changes before uploading?

Astuce

Si vous devez compiler manuellement dans un autre terminal, sélectionnez « Non » et compilez vous-même, puis continuez.

Étape 11 : Envoyer le bundle

Envoyez votre bundle d’application mis à jour vers Capgo.

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

CLI exécute :

npx @capgo/cli@latest bundle upload

Astuce

Mises à jour delta avec mises à jour instantanées : Si vous avez activé les mises à jour instantanées à l’étape 4, CLI vous demandera automatiquement si vous souhaitez activer les mises à jour delta. Les mises à jour delta n’envoient que les fichiers modifiés entre les versions, au lieu du bundle entier. Comme seuls quelques fichiers changent généralement entre deux mises à jour, les téléchargements sont beaucoup plus rapides. Sélectionnez Oui pour la meilleure expérience avec les mises à jour instantanées.

Prompt des mises à jour delta (si un mode d’application instantanée est activé) :

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with instant updates)

Attention

Pour les monorepos, vous devrez peut-être fournir des chemins supplémentaires à votre package.json et node_modules.

Succès :

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

Étape 12 : Tester la mise à jour sur l'appareil

Il est temps de voir la mise à jour en action !

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

Pour des mises à jour instantanées :

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

Pour des mises à jour standard :

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

Surveiller les logs :

❓ Monitor Capgo logs to verify the update worked?

Si vous sélectionnez Oui, vous verrez les logs en direct de votre appareil montrant le processus de mise à jour.

Étape 13 : Terminé

Welcome onboard ✈️!

Félicitations ! Vous avez configuré avec succès les live updates Capgo de votre application.

Ce que vous avez accompli

Après avoir terminé l’onboarding, vous disposez de :

✅ Application enregistrée

Votre application est enregistrée dans Capgo avec un canal de production

✅ Plugin installé

Le plugin Capacitor Updater est installé et configuré

✅ Code intégré

L’intégration code a été ajoutée à votre application

✅ Mise à jour testée

Vous avez déployé avec succès et reçu un live update

Workflow quotidien

Pour les mises à jour suivantes, utilisez :

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

Pour plus d’options de déploiement, voir Déployer un Live Update.

Reprendre l’onboarding

Si vous quittez le processus d'onboarding, vous pouvez le reprendre à tout moment :

npx @capgo/cli@latest init [APIKEY]

Vous verrez :

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

Astuce

La progression est sauvegardée localement, vous pouvez donc quitter et reprendre l'onboarding en toute sécurité.

Troubleshooting

Aucun environnement de développement

Problème : Ni Xcode ni SDK Android ne sont détectés.

Solution :

• Pour iOS: Installer Xcode (macOS uniquement)
• Pour Android: Installer Android Studio

ID d’application déjà utilisé

Problème : Votre ID d’application est déjà enregistré.

Solution : Choisissez l’une des alternatives suggérées ou saisissez un ID d’application personnalisé en notation de domaine inversé.

Script de build manquant

Problème : Aucun build script trouvé dans package.json.

Solution : Ajoutez un build script à votre package.json:

{
  "scripts": {
    "build": "your-build-command"
  }
}

Échec de l’injection automatique

Problème : CLI ne peut pas injecter automatiquement l'intégration code.

Solution : Ajoutez code manuellement à votre fichier principal :

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Version de Capacitor trop ancienne

Problème : Votre version de Capacitor est inférieure à la v5.

Solution : Upgrade Capacitor to v5 or higher:

• Passage à Capacitor 5
• Passage à Capacitor 6
• Mise à niveau vers Capacitor 7

Étapes suivantes

Maintenant que l’onboarding est terminé, explorez ces sujets :

Checklist de configuration initiale

Configurez canaux, CI et upload delta une seule fois pour une stabilité à long terme

Déployer les mises à jour

Apprenez à déployer des mises à jour depuis le dashboard Capgo

Types de mise à jour

Référence de tous les types de live update : moment d’application, conditions de délai, blocage de version et livraison

Intégration CI/CD

Automatisez vos déploiements de mises à jour avec CI/CD

Canaux

Gérez plusieurs flux de mises à jour avec des canaux

Chiffrement

Sécurisez vos mises à jour avec un chiffrement de bout en bout

Comportement de mise à jour

Personnalisez quand et comment les mises à jour sont appliquées (direct, delta, etc.)

Obtenir de l'aide

Si vous rencontrez des problèmes lors de l'onboarding :

• Consultez la Guide de dépannage
• Rejoignez le Communauté Discord
• Consultez l’ FAQ
• Contact Support

Continuez avec le guide d’onboarding CLI

Si vous utilisez Guide d'onboarding CLI pour planifier les opérations du dashboard et de API, connectez-l’avec Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans API Keys, Appareils pour les détails d'implémentation dans Devices, et Les bundles pour les détails d'implémentation dans Bundles.