CLI Einrichtungsleitfaden

Schnelle Übersicht

Das Capgo CLI bietet eine interaktive Einrichtung, die für Ihr Capacitor-Anwendungs lebendige Updates einrichtet. Sie werden:

1. ✅ Ihr Anwendungs bei Capgo registrieren
2. 🔌 Den Updater-Plugin installieren und konfigurieren
3. 🚀 Ihre erste lebendige Aktualisierung bereitstellen
4. 📱 Die Aktualisierung auf Ihrem Gerät testen

Geschätzte Zeit: 10-20 Minuten (je nach Internetgeschwindigkeit und Aufbaudauer)

Tip

Die Einrichtung ist vollständig wieder aufnehmbar - verlassen Sie sie jederzeit und setzen Sie sich später an dem Punkt fort, an dem Sie aufgehört haben.

Starten Sie die Einrichtung

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

npx @capgo/cli@latest init [APIKEY]

Sie sehen die Begrüßungsnachricht:

Capgo onboarding 🛫

Was Während der Einrichtung passiert

Der CLI-Schlüssel führt Sie durch 13 interaktive Schritte:

Einrichtungsphase (Schritte 1-6):

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

Testphase (Schritte 7-12):

• Bauen Sie Ihre App und führen Sie sie auf einem Gerät/Emulator aus
• Machen Sie eine sichtbare code Änderung (automatisch oder manuell)
• Laden Sie die aktualisierte Bundle auf Capgo hoch
• Sie sehen das Live-Update auf Ihrem Gerät in Echtzeit auftauchen

Abschluss (Schritt 13):

• Ihr App ist bereit für Live-Updates! 🎉

Der 13-Schritt-Startprozess

Schritt 1: Überprüfung der Voraussetzungen

Die CLI überprüft Ihr Entwicklungsumfeld, um sicherzustellen, dass Sie die erforderlichen Tools installiert haben.

Überprüft werden:

• Xcode (nur macOS) - für die iOS-Entwicklung
• Android SDK - für 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 Sie gestellt werden könnten:

Vorsicht

Wenn keine Entwicklungsumgebung ermittelt wird, werden Sie gefragt, ob Sie fortfahren möchten. Es wird empfohlen, mindestens eine Plattform vorher zu installieren.

Schritt 2: Hinzufügen Ihrer App

Der CLI wird dich in Capgo anmelden und deine App zu deinem Account hinzufügen.

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

❓ Add {appId} in Capgo?

Wenn dein App-ID bereits vergeben ist:

Der CLI wird Alternativen vorschlagen:

❌ 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 eine Vorschlag auswählen oder eine benutzerdefinierte App-ID eingeben.

Hinweis

App-IDs müssen in umgekehrter Domänennotation folgen (z.B. com.example.myapp)

Schritt 3: Erstellung von Produktionskanal

Kanäle ermöglichen dir, verschiedene Aktualisierungsströme für deine App zu verwalten.

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

Tip

Keine Sorge! Dies ist nur für lokale Tests während der Einrichtung gedacht. Die Erstellung eines "Produktions"-Kanals bedeutet nicht, dass Ihre Updates sofort an Kunden gehen werden. Sie haben die volle Kontrolle darüber, wann Updates bereitgestellt werden. Ja es sei denn, Sie haben spezifische Kanal-Anforderungen.

Wenn Sie Ja wählen:

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

Ein Produktionskanal wird erstellt und als Standardkanal festgelegt. Dies ist die empfohlene Option für die meisten Benutzer.

Wenn Sie Nein wählen:

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

Sie müssen die Kanäle später manuell erstellen und konfigurieren.

• Alternativ können Sie: capacitor.config.ts Den Kanal in Ihrem
• Datei setChannel() Mit der JavaScript
• Configure channels later from the Capgo web console

Kanäle später aus der __CAPGO_KEEP_0__ Web-Konsole konfigurieren

The CLI will install the @capgo/capacitor-updater Der Capacitor installiert das

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

Zur Vorschau kopieren

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

Vorsicht

Capgo unterstützt nur Capacitor v5 und höher. Wenn Sie eine ältere Version verwenden, müssen Sie sich zuerst aktualisieren.

Option für sofortige Aktualisierungen:

Nach der Installation werden Sie gefragt:

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

Tipps

Was sind sofortige Aktualisierungen? Mit sofortigen Aktualisierungen aktiviert, wird Ihre App sofort aktualisiert, wenn sie im Hintergrund läuft und neu gestartet wird. Dies funktioniert reibungslos, weil Capgo Aktualisierungen weltweit in weniger als 300 ms verteilen kann. Ohne es (Standardmodus), werden Aktualisierungen im Hintergrund heruntergeladen und auf dem nächsten App-Neustart angewendet. Sofortige Aktualisierungen sind großartig für schnellere Iterationen während der Entwicklung und kritische Fehlerbehebungen in der Produktion.

Wenn Sie Ja auswählen:

• Aktualisierungen werden so konfiguriert, dass sie sofort angewendet werden, wenn die App im Hintergrund läuft und neu gestartet wird
• directUpdate: 'always' und autoSplashscreen: true wird in Ihre Konfiguration aufgenommen
• Ihr capacitor.config.ts wird automatisch aktualisiert
• Delta-Updates wird automatisch aktiviert - dies sendet nur die Dateien, die sich zwischen den Updates geändert haben, anstatt des gesamten Bundles, was die Updates viel schneller macht

Wenn Sie "Nein" auswählen:

• Updates werden die Standardverhalten verwenden (Hintergrundherunterladen, Anwendung auf nächsten Neustart anwenden)
• Sie können Instant-Updates immer noch aktivieren, indem Sie Ihre capacitor.config.ts

Schritt 5: Hinzufügen der Integration Code

Der CLI wird die erforderlichen code automatisch in Ihre Hauptanwendungsdatei einfügen

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

Was wird hinzugefügt:

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

CapacitorUpdater.notifyAppReady()

Projekttyp-Detektion:

• Nuxt.js: Erstellt plugins/capacitorUpdater.client.ts
• Andere Frameworks: Fügt Ihrem Haupt-Einstiegsskript hinzu

Tipp

Wenn die automatische Injection fehlschlägt,kannst du den 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ügen Sie dies Ihrem Haupt-Einstiegsskript hinzu (z.B., main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Platzieren Sie dies code nach Ihren Imports und vor der Initialisierung Ihrer App. Weitere Details finden Sie im Anwendungsleitfaden.

Schritt 6: Verschlüsselung einrichten (Optional)

Die Ende-zu-Ende-Verschlüsselung fügt einem zusätzlichen Sicherheitslevel 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.

Wenn Sie die Verschlüsselung aktivieren, wird das CLI:

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

Schritt 7: Plattform auswählen

Wählen Sie während der Einrichtung die zu testende Plattform.

📱 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

Tipps

Dies beeinflusst nur den Einrichtungsprozess. Ihre endgültige App unterstützt alle Plattformen.

Schritt 8: Erstellen Sie Ihr Projekt

Der CLI wird Ihr App erstellen und synchronisieren mit Capacitor.

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

Was passiert:

1. Erkennen Sie den Projekttyp
2. Ausführen Ihres Build-Skripts
3. Ausführen npx cap sync {platform}

Wenn Build-Skript fehlt:

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

Schritt 9: Ausführen auf Gerät

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: Ändern Sie zum Testen

Jetzt ist es Zeit, das Update-System von Capgo zu testen, indem Sie eine sichtbare Änderung vornehmen.

🎯 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

Automatikmodus: Das CLI wird Ihre Dateien automatisch ändern, um eine sichtbare Testbanner oder Änderung hinzuzufügen.

Manueller Modus: Sie machen Ihre eigenen Änderungen (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 bauen:

❓ Build {appId} with changes before uploading?

Tipp

Wenn Sie manuell in einem anderen Terminal bauen müssen, wählen Sie "Nein" und bauen Sie selbst, dann können Sie fortfahren.

Schritt 11: Bundle hochladen

Hochladen Sie Ihr aktualisiertes App-Bundle auf Capgo.

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

Die CLI läuft:

npx @capgo/cli@latest bundle upload

Tipps

Delta-Updates mit Direct Update: Wenn Sie in Schritt 4 Instant-Updates (Direct Update) aktiviert haben, fragt die CLI automatisch, ob Sie Delta-Updates aktivieren möchten. Delta-Updates senden nur die Dateien, die zwischen den Versionen geändert wurden, anstatt den gesamten Bundle. Da normalerweise nur wenige Dateien zwischen den Updates geändert werden, macht dies die Downloads viel schneller. Wählen Sie Ja für die beste Erfahrung mit Instant-Updates.

Delta-Updates-Angebot (wenn Direct Update aktiviert ist):

💡 Direct Update (instant updates) is enabled in your config
   Delta updates send only changed files instead of the full bundle

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

Vorsicht

Für Monorepos müssen Sie möglicherweise 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: Testen Sie die Aktualisierung auf dem Gerät

Jetzt sehen Sie die Aktualisierung in Aktion!

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

Für sofortige Aktualisierungen:

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

Für standardmäßige Aktualisierungen:

📱 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

Protokolle überwachen:

❓ Monitor Capgo logs to verify the update worked?

Wenn Sie Ja, sehen Sie live Protokolle von Ihrem Gerät, die den Update-Prozess anzeigen.

Schritt 13: Abschluss

Welcome onboard ✈️!

Herzlichen Glückwunsch! Sie haben erfolgreich Capgo-Live-Updates für Ihre App eingerichtet.

Was Sie erreicht haben

Nach Abschluss der Einrichtung haben Sie:

✅ App Registriert

Ihre App ist in Capgo mit einem Produktionskanal registriert

✅ Plugin Installiert

Das Capacitor-Updater-Plugin ist installiert und konfiguriert

✅ Code Integriert

Die Integration code wurde in Ihre App hinzugefügt

✅ Update Getestet

Sie haben erfolgreich ein Live-Update bereitgestellt und erhalten haben

Tägliche Workflow

Für nachfolgende Updates verwenden Sie:

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

Für weitere Bereitstellungsoptionen siehe Live-Update bereitstellen.

Wiederaufnahme der Einrichtung

Wenn Sie das Einrichtungsprozess verlassen, können Sie jederzeit fortfahren:

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?

Hinweis

Der Fortschritt wird lokal gespeichert, sodass Sie sicher aussteigen und den Einrichtungsprozess fortsetzen können.

Fehlersuche

Keine Entwicklungsumgebung

Problem: Kein Xcode- oder Android-SDK-Entwickler wurde erkannt.

Lösung:

• Für iOS:: Installieren Sie Xcode __CAPGO_KEEP_0__
• Für Android: Installieren Android Studio

App-ID bereits vergeben

Problem: Ihre App-ID ist bereits registriert.

Lösung: Wählen Sie eine der vorgeschlagenen Alternativen oder geben Sie eine benutzerdefinierte App-ID in umgekehrter Domänennotation ein.

Build-Skript fehlt

Problem: Kein Build-Skript gefunden in package.json.

Lösung: Fügen Sie ein Build-Skript zu Ihrem package.json:

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

Auto-Injektion fehlgeschlagen

Problem: CLI kann die Integration code nicht automatisch einbinden.

Lösung: Fügen Sie code manuell in Ihre Hauptdatei ein:

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

CapacitorUpdater.notifyAppReady()

Capacitor Version Too Alt

Problem: Ihre Capacitor Version liegt unter v5.

Lösung: Aktualisieren Sie Capacitor auf v5 oder höher:

• Aktualisierung auf Capacitor 5
• Aktualisierung auf Capacitor 6
• Aktualisierung auf Capacitor 7

Nächste Schritte

Nachdem Sie die Einrichtung abgeschlossen haben, erkunden Sie diese Themen:

Updates bereitstellen

Erfahren Sie, wie Sie Updates aus der Capgo-Oberfläche bereitstellen

Update-Typen

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

CI/CD-Integration

Automatisieren Sie die Bereitstellung Ihrer Updates mit CI/CD

Kanäle

Verwalten Sie mehrere Update-Ströme mit Kanälen

Verschlüsselung

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

Update-Verhalten

Konfigurieren Sie, wann und wie Updates angewendet werden (direkt, Delta usw.)

Hilfe erhalten

Wenn Sie während der Einrichtung Probleme auftreten:

• Überprüfen Sie das Troubleshooting-Hilfe
• Beitreten Sie zur Discord-Gemeinschaft
• Überprüfen Sie die Häufig gestellten Fragen (FAQ)
• Kontakt Support