Guide d'onboarding CLI

Aperçu rapide

Le 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 (selon votre connexion et le temps de build)

Astuce

L'onboarding est entièrement reprise — quittez à tout moment et reprenez plus tard là où vous vous étiez 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

Le 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 optionnellement 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 simulateur
• Effectuez un changement code visible (automatique ou manuel)
• Envoyez le bundle mis à jour vers Capgo
• Voyez live update apparaître sur votre appareil en temps réel

Finalisation (É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

Le CLI vérifie votre environnement de développement pour s'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 ont été trouvés :

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

⚠️ Aucun environnement trouvé :

⚠️ 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 pourraient 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 votre app ID est déjà utilisé :

CLI vous suggérera 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 app ID personnalisé.

Remarque

Les app ID doivent suivre la notation de domaine inversé (ex : com.example.myapp)

Étape 3 : Créer un 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

Pas d’inquiétude ! Ceci sert uniquement aux tests locaux pendant 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 exigences 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
• Utiliser la méthode JavaScript setChannel() méthode 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+ : installations de la dernière version

Attention

Capgo prend uniquement en charge Capacitor v5 et versions supérieures. Si vous utilisez une version plus ancienne, vous devrez d'abord la mettre à jour.

Option des 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

Que sont 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 de manière fluide car Capgo peut distribuer des mises à jour dans le monde entier en moins de 300 ms. Sans cela (mode standard), les mises à jour se téléchargent en arrière-plan et s'appliquent au prochain redémarrage de l'app. Les mises à jour instantanées sont idéales pour itérer plus vite pendant le développement et pour les correctifs de bugs critiques en production.

Si vous sélectionnez Oui :

• Les mises à jour seront configurées pour s'appliquer immédiatement lorsque l'app est mise en arrière-plan et rouverte
• autoUpdate: 'always' et autoSplashscreen: true sera ajouté à votre config
• @capacitor/splash-screen sera installé s'il est manquant, avec launchAutoHide: false
• Votre capacitor.config.ts sera mis à jour automatiquement
• Mises à jour delta rester activé. L'application instantanée (always, atInstall, onLaunch) devrait continuer à utiliser npx @capgo/cli@latest bundle upload --delta pour que seuls les fichiers modifiés soient téléchargés, évitant ainsi l'attente d'un zip complet

Si vous sélectionnez Non :

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

Étape 5 : Ajouter l'intégration Code

CLI injectera 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: 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 application. Pour plus de détails, consultez le Ajouter un guide d'application.

É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 est disponible uniquement pour Capacitor v6 et versions supérieures.

Si vous activez le chiffrement, CLI va :

1. Générer des clés de chiffrement
2. Proposer de synchroniser votre configuration Capacitor

Étape 7 : Sélectionner la plateforme

Choisissez la plateforme avec laquelle 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 supportera 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étection du type de projet
2. Exécution de votre script de build
3. Exécute des npx cap sync {platform}

Si le script de build est manquant :

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

Étape 9 : Exécuter sur un appareil

Testez la version initiale de votre application 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 : Effectuer un changement de test

Il est maintenant temps de tester le système de mise à jour de Capgo en effectuant 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 : CLI modifiera automatiquement vos fichiers pour ajouter une bannière de test visible ou une modification.

Mode manuel : Vous effectuez vos propres modifications (ex: changer le texte, les couleurs ou ajouter des éléments).

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

Build avec modifications :

❓ Build {appId} with changes before uploading?

Astuce

Si vous devez lancer un build manuellement dans un autre terminal, sélectionnez « Non », lancez votre build, puis continuez.

Étape 11 : Upload du bundle

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

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

Le CLI exécute :

npx @capgo/cli@latest bundle upload

Astuce

Les delta updates avec mises à jour instantanées : Si vous avez activé les instant updates à l'étape 4, le CLI vous demandera automatiquement si vous souhaitez activer les delta updates. Les delta updates n'envoient que les fichiers modifiés entre les versions au lieu du bundle complet. Comme seuls quelques fichiers changent généralement entre deux mises à jour, cela rend les téléchargements beaucoup plus rapides. Sélectionnez Oui pour une expérience optimale avec les instant updates.

Prompt de delta updates (si le mode instant apply 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 affichant le processus de mise à jour.

Étape 13 : Finalisation

Welcome onboard ✈️!

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

Ce que vous avez accompli

Après avoir terminé l'onboarding, vous avez :

✅ Application enregistrée

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

✅ Plugin installé

Le plugin Updater Capacitor 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é et reçu avec succès 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, consultez 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 l'SDK d'Android n'ont été détectés.

Solution :

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

App ID déjà utilisé

Problème : Votre app ID est déjà enregistrée.

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 script de build trouvé dans package.json.

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

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

Échec de l'auto-injection

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
• Passage à Capacitor 7

Étapes suivantes

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

Checklist de configuration initiale

Configurez vos canaux, la CI et l'upload delta pour une stabilité à long terme

Déployer des mises à jour

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

Types de mise à jour

Référence des types de live updates : timing d'application, conditions de délai, blocage de version et livraison

Intégration CI/CD

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

Canaux

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

Chiffrement

Sécurisez vos mises à jour avec le 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 :

• Vérifiez la Guide de dépannage
• Rejoignez la Communauté Discord
• Consultez la FAQ
• Contacter Support

Continuer 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’à Aperçu de API pour les détails d'implémentation dans l'aperçu de API, Introduction pour les détails d'implémentation dans l'Introduction, Clés API pour les détails d'implémentation dans les clés API, Appareils pour les détails d'implémentation dans Devices, et Bundles pour les détails d'implémentation dans Bundles.