CLI Onboarding-Guide

Schneller Überblick

Die Capgo CLI bietet ein interaktives Onboarding, das Live Updates für Ihre Capacitor-App einrichtet. Sie werden:

1. ✅ Ihre App in Capgo registrieren
2. 🔌 Das Updater-Plugin installieren und konfigurieren
3. 🚀 Ihr erstes live update deployen
4. 📱 Das Update auf Ihrem Gerät testen

Geschätzte Zeit: 10–20 Minuten (abhängig von Ihrer Internetgeschwindigkeit und Build-Zeit)

Tipp

Das Onboarding ist vollständig fortsetzbar – beenden Sie es jederzeit und setzen Sie später dort fort, wo Sie aufgehört haben.

Onboarding starten

Führen Sie den Onboarding-Befehl mit Ihrem API-Schlüssel aus:

npx @capgo/cli@latest init [APIKEY]

Sie sehen die Willkommensnachricht:

Capgo onboarding 🛫

Was beim Onboarding passiert

Der CLI führt Sie durch 13 interaktive Schritte:

Setup-Phase (Schritte 1–6):

• Prüfen Sie Ihre Entwicklungsumgebung (Xcode/Android Studio)
• Fügen Sie Ihre App zu Capgo hinzu und erstellen Sie einen Produktions-Channel
• Installiere das @capgo/capacitor-updater Plugin
• Injizieren Sie das erforderliche code in Ihre App
• Aktivieren Sie optional die Ende-zu-Ende-Verschlüsselung
• Wählen Sie eine Plattform für Tests (iOS oder Android)

Testphase (Schritte 7–12):

• App bauen und auf einem Gerät/Simulator ausführen
• Eine sichtbare code-Änderung vornehmen (automatisch oder manuell)
• Lade das aktualisierte Bundle auf Capgo hoch
• Sieh zu, wie live update in Echtzeit auf deinem Gerät erscheint

Abschluss (Schritt 13):

• Deine App ist bereit für Live Updates! 🎉

Der 13-stufige Onboarding-Prozess

Schritt 1: Voraussetzungen prüfen

CLI prüft deine Entwicklungsumgebung, um sicherzustellen, dass die erforderlichen Tools installiert sind.

Was geprüft wird:

• Xcode (nur macOS) – für iOS-Entwicklung
• Android SDK - für die Android-Entwicklung

Mögliche Ergebnisse:

✅ Beide Umgebungen gefunden:

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

⚠️ Keine Umgebung gefunden:

⚠️ 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

Fragen, die gestellt werden können:

Achtung

Wenn keine Entwicklungsumgebung erkannt wird, wirst du gefragt, ob du fortfahren möchtest. Es wird empfohlen, vor dem Fortfahren mindestens eine Plattform zu installieren.

Schritt 2: Deine App hinzufügen

Mit CLI loggst du dich bei Capgo ein und fügst deine App deinem Account hinzu.

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

❓ Add {appId} in Capgo?

Falls deine App-ID bereits vergeben ist:

Die CLI schlägt Alternativen vor:

❌ 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?

Du kannst einen Vorschlag wählen oder eine eigene App-ID eingeben.

Hinweis

App-IDs müssen der Reverse-Domain-Notation folgen (z. B. com.example.myapp)

Schritt 3: Production Channel erstellen

Mit Channels verwaltest du verschiedene Update-Streams für deine App.

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

Tipp

Keine Sorge! Das dient nur dem lokalen Testen während des Onboardings. Die Erstellung eines „production“-Channels bedeutet nicht, dass deine Updates sofort live an Kunden ausgeliefert werden. Du hast die volle Kontrolle darüber, wann Updates deployed werden. Wähle Ja außer du hast spezifische Anforderungen an Channels.

Wenn du Ja wählst:

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

Ein Production-Channel wird erstellt und als Standard festgelegt. Dies ist die empfohlene Option für die meisten Nutzer.

Wenn du Nein wählst:

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

Später musst du Channels manuell erstellen und konfigurieren. Alternativ kannst du:

• Den Channel in deiner capacitor.config.ts Datei
• Nutze die JavaScript- setChannel() Methode, um den Channel dynamisch zu setzen
• Channels später über die Capgo Web-Konsole konfigurieren

Schritt 4: Updater-Plugin installieren

Die CLI installiert das @capgo/capacitor-updater Plugin, das mit deiner Capacitor-Version kompatibel ist.

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

Versionskompatibilität:

• Capacitor 5: Installationen @capgo/capacitor-updater v5
• Capacitor 6: Installationen @capgo/capacitor-updater v6
• Capacitor 7: Installationen @capgo/capacitor-updater v7
• Capacitor 8+: Installiert die neueste Version

Achtung

Capgo unterstützt nur Capacitor v5 und höher. Wenn du eine ältere Version verwendest, musst du sie zuerst aktualisieren.

Option für Instant Updates:

Nach der Installation wirst du gefragt:

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

Tipp

Was sind Instant Updates? Mit aktivierten Instant Updates wendet deine App Updates sofort an, wenn sie in den Hintergrund geschickt und wieder geöffnet wird. Das funktioniert nahtlos, da Capgo Updates weltweit in unter 300 ms ausliefern kann. Ohne diese Funktion (Standardmodus) werden Updates im Hintergrund heruntergeladen und beim nächsten Neustart der App angewendet. Instant Updates eignen sich hervorragend für schnellere Iterationen während der Entwicklung und kritische Bugfixes im Produktivbetrieb.

Wenn Sie Ja auswählen:

• Updates werden so konfiguriert, dass sie sofort angewendet werden, wenn die App in den Hintergrund versetzt und erneut geöffnet wird
• autoUpdate: 'always' und autoSplashscreen: true wird deiner Config hinzugefügt
• @capacitor/splash-screen wird installiert, falls nicht vorhanden, mit launchAutoHide: false
• Dein capacitor.config.ts wird automatisch aktualisiert
• Delta-Updates bleiben aktiviert. Sofort anwenden (always, atInstall, onLaunch) sollte weiterhin verwenden npx @capgo/cli@latest bundle upload --delta damit nur geänderte Dateien heruntergeladen werden und der Nutzer nicht auf ein komplettes ZIP wartet

Wenn du Nein wählst:

• Updates nutzen das Standardverhalten (Download im Hintergrund, Anwenden beim nächsten Neustart)
• Du kannst Instant Updates später jederzeit aktivieren, indem du deine capacitor.config.ts

Schritt 5: Integration Code hinzufügen

Die CLI fügt die erforderliche code automatisch in Ihre Hauptanwendungsdatei ein.

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

Was hinzugefügt wird:

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

CapacitorUpdater.notifyAppReady()

Erkennung des Projekttyps:

• Nuxt.js: Erstellt plugins/capacitorUpdater.client.ts
• Andere Frameworks: Fügt deiner Haupt-Entry-Datei hinzu

Tipp

Wenn die Auto-Injection fehlschlägt, kannst du code manuell in deine Hauptanwendungsdatei einfügen:

Für Nuxt.js: Erstellen plugins/capacitorUpdater.client.ts:

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

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

Für andere Frameworks: Füge deiner Haupt-Entry-Datei hinzu (z. B. main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Platziere dieses code nach deinen Imports und vor der App-Initialisierung. Weitere Details findest du unter App hinzufügen – Anleitung.

Schritt 6: Verschlüsselung einrichten (optional)

Ende-zu-Ende-Verschlüsselung fügt eine zusätzliche Sicherheitsebene für Ihre Updates hinzu.

🔐 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?

Hinweis

Verschlüsselung ist nur für Capacitor v6 und höher verfügbar.

If you enable encryption, the CLI will:

1. Verschlüsselungsschlüssel generieren
2. Angebot machen, Ihre Capacitor-Konfiguration zu synchronisieren

Schritt 7: Plattform auswählen

Wähle die Plattform, mit der du während des Onboardings testen möchtest.

📱 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

Tipp

Dies betrifft nur den Onboarding-Prozess. Ihre finale App unterstützt alle Plattformen.

Schritt 8: Projekt bauen

Die CLI baut Ihre App und synchronisiert sie mit Capacitor.

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

Was passiert:

1. Erkennt Ihren Projekttyp
2. Führt Ihr Build-Skript aus
3. Führt npx cap sync {platform}

Falls das Build-Skript fehlt:

Sie werden gefragt, ob Sie den Build überspringen oder ein Build-Skript zu Ihrem hinzufügen möchten package.json.

Schritt 9: Auf dem Gerät ausführen

Testen Sie die erste Version Ihrer App auf einem Gerät oder Simulator.

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

Wenn Sie auswählen Ja:

(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

Schritt 10: Eine Teständerung vornehmen

Jetzt testen wir das Update-System von Capgo mit einer sichtbaren Änderung.

🎯 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

Auto-Modus: CLI ändert deine Dateien automatisch, um ein sichtbares Test-Banner oder eine Änderung hinzuzufügen.

Manueller Modus: Du führst deine eigenen Änderungen durch (z. B. Text, Farben ändern oder Elemente hinzufügen).

Versionsverwaltung:

❓ 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

Mit Änderungen builden:

❓ Build {appId} with changes before uploading?

Tipp

Wenn du manuell in einem anderen Terminal bauen musst, wähle „Nein“ aus, baue selbst und fahre dann fort.

Schritt 11: Bundle hochladen

Lade dein aktualisiertes App-Bundle auf Capgo hoch.

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

CLI führt Folgendes aus:

npx @capgo/cli@latest bundle upload

Tipp

Delta-Updates mit sofortigen Updates: Wenn Sie in Schritt 4 sofortige Updates aktiviert haben, fragt CLI automatisch ab, ob Sie Delta-Updates aktivieren möchten. Delta-Updates senden nur die Dateien, die sich zwischen den Versionen geändert haben, anstatt das gesamte Bundle. Da in der Regel nur wenige Dateien zwischen Updates geändert werden, sind die Downloads deutlich schneller. Wählen Sie Ja für die beste Erfahrung mit Instant Updates.

Delta-Update-Prompt (falls ein Instant-Apply-Modus aktiviert ist):

💡 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)

Achtung

Bei Monorepos müssen Sie eventuell zusätzliche Pfade zu Ihrem package.json und node_modules.

Erfolg:

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

Schritt 12: Update auf dem Gerät testen

Zeit, das Update in Aktion zu sehen!

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

Für sofortige Updates:

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

Für Standard-Updates:

📱 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

Logs überwachen:

❓ Monitor Capgo logs to verify the update worked?

If you select Jaauswählen, sehen Sie Live-Logs von Ihrem Gerät, die den Update-Prozess anzeigen.

Schritt 13: Abschluss

Welcome onboard ✈️!

Glückwunsch! Du hast Capgo Live Updates für deine App erfolgreich eingerichtet.

Das hast du geschafft

Nach dem Onboarding hast du Folgendes erledigt:

✅ App registriert

Deine App ist in Capgo mit einem Production-Channel registriert

✅ Plugin installiert

Das Capacitor Updater-Plugin ist installiert und konfiguriert

✅ Code integriert

Die code-Integration ist zu deiner App hinzugefügt

✅ Update getestet

Du hast erfolgreich deployed und einen live update erhalten

Täglicher Workflow

Für nachfolgende Updates verwendest du:

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

Weitere Deployment-Optionen findest du unter Live Update deployen.

Onboarding fortsetzen

Wenn du den Onboarding-Prozess verlässt, kannst du ihn jederzeit fortsetzen:

npx @capgo/cli@latest init [APIKEY]

Sie sehen:

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

Tipp

Der Fortschritt wird lokal gespeichert, sodass Sie den Onboarding-Prozess sicher beenden und später fortsetzen können.

Fehlerbehebung

Keine Entwicklungsumgebung

Problem: Weder Xcode noch Android SDK wurde erkannt.

Lösung:

• Für iOS: Installieren Xcode (nur macOS)
• Für Android: Installieren Android Studio

App ID bereits vergeben

Problem: Ihre App-ID ist bereits registriert.

Lösung: Wähle eine der vorgeschlagenen Alternativen oder gib eine eigene App-ID in Reverse-Domain-Notation ein.

Build-Script fehlt

Problem: Kein Build Script gefunden in package.json.

Lösung: Füge ein Build Script zu deiner package.json:

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

Auto-Injection fehlgeschlagen

Problem: CLI kann die Integration code nicht automatisch injizieren.

Lösung: Füge code manuell zu deiner Hauptdatei hinzu:

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

CapacitorUpdater.notifyAppReady()

Capacitor-Version zu alt

Problem: Deine Capacitor-Version ist älter als v5.

Lösung: Upgrade Capacitor auf v5 oder höher:

• Upgrade auf Capacitor 5
• Upgrade auf Capacitor 6
• Upgrade auf Capacitor 7

Nächste Schritte

Jetzt, wo das Onboarding abgeschlossen ist, erkunde diese Themen:

Checkliste für die Ersteinrichtung

Konfiguriere Channels, CI und Delta-Uploads einmalig für langfristige Stabilität

Updates deployen

Lerne, wie du Updates über das Capgo-Dashboard deployst

Update-Typen

Referenz aller OTA-Update-Typen: Anwendungszeitpunkt, Verzögerungsbedingungen, Versionsblockierung und Auslieferung

CI/CD-Integration

Automatisieren Sie Ihre Update-Deployments mit CI/CD

Kanäle

Verwalten Sie mehrere Update-Streams mit Channels

Verschlüsselung

Sichern Sie Ihre Updates mit Ende-zu-Ende-Verschlüsselung

Update-Verhalten

Passen Sie an, wann und wie Updates angewendet werden (direct, delta usw.)

Hilfe erhalten

Wenn Sie während des Onboardings auf Probleme stoßen:

• Schau in die Troubleshooting-Guide
• Werde Teil von Discord-Community
• Überprüfe die FAQ
• Kontakt Support

Weiterlesen im CLI Onboarding Guide

Wenn du es nutzt CLI Onboarding-Guide um Dashboard- und API-Operationen zu planen, verbinde es mit API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für die Implementierungsdetails in API Keys, Geräte für die Implementierungsdetails in Devices und Bundles für die Implementierungsdetails in Bundles.