CLI Guide d'abordage

Vue d'ensemble rapide

Le Capgo CLI fournit une expérience d'abordage interactive qui configure les mises à jour en temps réel pour votre application Capacitor. Vous allez :

1. ✅ Inscrivez votre application sur Capgo
2. 🔌 Installez et configurez le plugin de mise à jour
3. 🚀 Déployez votre première mise à jour en temps réel
4. 📱 Testez la mise à jour sur votre appareil

Temps estimé : 10-20 minutes (varie en fonction de votre vitesse de connexion et du temps de construction)

Conseil

Le processus de démarrage est entièrement résumable - vous pouvez quitter à tout moment et continuer plus tard à partir du point où vous avez arrêté.

Démarrer le processus de démarrage

Exécutez la commande de démarrage avec votre clé API :

npx @capgo/cli@latest init [APIKEY]

Vous verrez le message d'accueil :

Capgo onboarding 🛫

Ce qui se passe pendant le processus de démarrage

La clé CLI vous guidera à travers 13 étapes interactives :

Phase de mise en place (Étapes 1-6) :

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

Phase de test (Étapes 7-12) :

• Construisez votre application et exécutez-la sur un appareil/simulateur
• Apportez une modification visible de code (automatique ou manuelle)
• Envoyez le bundle mis à jour vers Capgo
• Voyez l'actualisation en direct apparaitre sur votre appareil en temps réel

Terminé (Étape 13):

• Votre application est prête pour les mises à jour en direct ! 🎉

Le Processus d'Onboarding en 13 Étapes

Étape 1 : Vérifiez les Prérequis

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

Ce qui est vérifié :

• Xcode (seulement macOS) - pour le développement iOS
• L'SDK Android - pour le développement Android

Résultats possibles :

✅ Les deux environnements 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 auxquelles vous pourriez être posées :

Attention

Si aucun environnement de développement n'est détecté, vous serez interrogé sur votre volonté de continuer. Il est recommandé d'installer au moins une plateforme avant de poursuivre.

Étape 2 : Ajouter votre application

Le 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 ID d'application est déjà pris :

Le CLI vous 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 entrer un ID d'application personnalisé.

Remarque

Les ID d'application doivent suivre la notation de domaine inversé (par exemple, com.example.myapp)

Étape 3 : Créer un canal de production

Les canaux vous permettent de gérer différents flux d'actualisation pour votre application.

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

Conseil

Ne vous inquiétez pas ! Cela ne concerne que la mise en œuvre locale pendant l'inscription. La création d'un canal « production » ne signifie pas que vos mises à jour seront immédiatement déployées auprès des clients. Vous avez le contrôle total sur la mise en œuvre des mises à jour. Sélectionnez Oui sauf si vous avez des exigences spécifiques pour les 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 comme canal 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"

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

• Configurez le canal dans votre capacitor.config.ts fichier
• Utilisez la méthode JavaScript pour définir dynamiquement le canal setChannel() Configurez les canaux plus tard à partir de la console web __CAPGO_KEEP_0__
• Configure channels later from the Capgo web console

Section intitulée « Étape 4 : Installer le plugin de mise à jour »

plugin compatible avec votre version CLI. @capgo/capacitor-updater plugin compatible with your Capacitor version.

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

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

• Capacitor 5: Installe @capgo/capacitor-updater v5
• Capacitor 6: Installe @capgo/capacitor-updater v6
• Capacitor 7: Installe @capgo/capacitor-updater v7
• Capacitor 8+: Installe la dernière version

Attention

Capgo ne supporte que Capacitor v5 et supérieur. Si vous utilisez une version plus ancienne, vous devrez d'abord la mettre à jour.

Option d'actualisation instantanée :

Après l'installation, vous serez interrogé :

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

Conseil

Qu'est-ce que les actualisations instantanées ? Lorsque les actualisations instantanées sont activées, votre application applique les mises à jour immédiatement lorsque l'application est mise en arrière-plan et rouvert. Cela fonctionne de manière fluide car Capgo peut distribuer les 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 lors du prochain redémarrage de l'application. Les actualisations instantanées sont excellentes pour une itération plus rapide pendant le développement et les correctifs critiques en production.

Si vous sélectionnez Oui :

• Les mises à jour seront configurées pour s'appliquer immédiatement lorsque l'application est mise en arrière-plan et rouvert
• autoUpdate: 'always' et autoSplashscreen: true sera ajouté à votre config
• Votre capacitor.config.ts sera mis à jour automatiquement
• Mises à jour Delta sera automatiquement activé - cela envoie uniquement les fichiers qui ont changé entre les mises à jour au lieu du bundle complet, ce qui rend les mises à jour beaucoup plus rapides

Si vous sélectionnez Non :

• Les mises à jour utiliseront le comportement standard (téléchargement en arrière-plan, application à la prochaine redémarrage)
• 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 injectera automatiquement les code requis dans votre fichier d'application principal.

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

What gets added:

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

CapacitorUpdater.notifyAppReady()

Détecte le type de projet :

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

Conseil

Si l'injection automatique échoue, vous pouvez ajouter 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 d'autres frameworks : Ajoutez à votre fichier d'entrée principal (par exemple, main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Placez ce code après vos importations et avant l'initialisation de votre application. Pour plus de détails, consultez le guide de l'application Guide de l'application : étape 6 - Configuration de l'encryption (facultatif).

Sous-titre : « Étape 6 : Configuration de l'encryption (facultatif) »

Copier dans le presse-papier

🔐 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

La cryptage n'est disponible que pour Capacitor v6 et versions ultérieures.

Si vous activez la cryptage, le CLI fera :

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

Étape 7 : Sélectionner la plateforme

Choisissez la plateforme pour tester lors de l'inscription.

📱 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

Conseil

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

Étape 8 : Construire votre projet

Le CLI construira votre application et la synchronisera avec Capacitor.

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

Ce qui se passe :

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

Si le script de construction est manquant :

Vous serez invité à sauter la construction ou à ajouter un script de construction à votre package.json.

Étape 9 : Exécuter sur appareil

Testez la première version 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 : Apportez une modification de test

Il est maintenant temps de tester le système d'actualisation de Capgo en apportant une modification 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 modifiera automatiquement vos fichiers pour ajouter un bandeau de test visible ou une modification.

Mode manuel : Vous apportez vos propres modifications (par exemple, modifier le texte, les couleurs ou ajouter des éléments).

Gestion de version :

❓ 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

Construire avec modifications :

❓ Build {appId} with changes before uploading?

Conseil

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

Étape 11 : Télécharger le Bundle

Téléchargez votre bundle d'application mise à jour sur Capgo.

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

Le CLI exécute :

npx @capgo/cli@latest bundle upload

Conseil

Mises à jour Delta avec mises à jour instantanées : Si vous avez activé les mises à jour instantanées dans l'étape 4, le CLI demandera automatiquement si vous souhaitez activer les mises à jour delta. Les mises à jour delta envoient uniquement les fichiers qui ont changé entre les versions au lieu du bundle complet. Puisque généralement, seuls quelques fichiers changent entre les mises à jour, cela rend les téléchargements beaucoup plus rapides. Sélectionnez Oui pour l'expérience la meilleure avec les mises à jour instantanées.

Invite de mise à jour delta (si un mode d'application instantané 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 le dispositif

Le 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 journaux :

❓ Monitor Capgo logs to verify the update worked?

Si vous sélectionnez Oui, vous verrez les journaux en direct de votre appareil montrant le processus d'actualisation.

Étape 13 : Complétion

Welcome onboard ✈️!

Félicitations ! Vous avez réussi à configurer les mises à jour en direct Capgo pour votre application.

Ce que vous avez accompli

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

✅ Application Enregistrée

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

✅ Plugin Installé

Le plugin de mise à jour Capacitor est installé et configuré

✅ Code Intégré

L'intégration code est ajoutée à votre application

✅ Mise à jour Testée

Vous avez réussi à déployer et à recevoir une mise à jour en direct

Flux de travail quotidien

Pour les mises à jour ultérieures, utilisez :

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

Pour plus d'options de déploiement, voir Déployer une mise à jour en direct.

Reprise de l'inscription

Si vous quittez le processus d'inscription, vous pouvez 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?

Conseil

Le progrès est sauvegardé localement, vous pouvez donc sortir en toute sécurité et reprendre le processus d'inscription.

Résolution des problèmes

Aucun environnement de développement

Problème : Ni Xcode ni Android SDK n'est détecté.

Solution :

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

L'ID de l'application est déjà pris

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

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

Manque de script de construction

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

Solution : Ajoutez un script de construction à 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()

Capacitor Version Too Vieille

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

Solution : Mettez à jour Capacitor vers v5 ou supérieur :

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

Étapes suivantes

Maintenant que vous avez terminé l'inscription, explorez ces sujets :

Liste de vérification de configuration unique

Configurez les canaux, CI et téléchargement delta une seule fois pour une stabilité à long terme

Déployer des Mises à jour

Apprenez à déployer des mises à jour à partir du tableau de bord Capgo

Types de Mises à jour

Référence de tous les types de mises à jour OTA : application de timing, conditions de retard, blocage de version et livraison

Intégration CI/CD

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

Canal

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

Chiffrement

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

Mise à jour du comportement

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'inscription :

• Vérifiez le Guide de dépannage
• Rejoignez la Communauté Discord
• Examinez le FAQ
• Contactez-nous Support

Continuez de CLI Guide de démarrage

Si vous utilisez CLI Guide de démarrage pour planifier le tableau de bord et les opérations API, connectez-le à API Vue d'ensemble pour les détails d'implémentation dans API Vue d'ensemble, Introduction pour les détails d'implémentation dans Introduction, API Clés pour les détails d'implémentation dans API Clés Appareils pour le détail d'implémentation dans Appareils, et Ensembles pour le détail d'implémentation dans Ensembles.