CLI Onboarding Guide

Schnelle Übersicht

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

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

Schätzung der Zeit: 10-20 Minuten (abhängig von Ihrer Internetgeschwindigkeit und der Bauzeit)

Tip

Die Einrichtung ist vollständig wieder aufnehmbar - beenden Sie sie jederzeit und setzen Sie sie später fort, wo Sie aufgehört haben.

Einrichtung starten

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

npx @capgo/cli@latest init [APIKEY]

Sie sehen die Begrüßungsnachricht:

Capgo onboarding 🛫

Was passiert während der Einrichtung

Der CLI wird Sie durch 13 interaktive Schritte führen:

Einrichtungsphase (Schritte 1-6):

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

Testphase (Schritte 7-12):

• Ihre App erstellen und auf einem Gerät/Emulator ausführen
• Eine sichtbare code Änderung (automatisch oder manuell) vornehmen
• Die aktualisierte Bundle auf Capgo hochladen
• Die lebendige Aktualisierung auf Ihrem Gerät in Echtzeit erscheinen sehen

Abschluss (Schritt 13):

• Ihre App ist für lebendige Aktualisierungen bereit! 🎉

Der 13-Schrittige Einrichtungsprozess

Schritt 1: Prüfung der Voraussetzungen

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

Was geprüft wird:

• Xcode (macOS nur) - für 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önnen:

Vorsicht

Wenn kein Entwicklungsumfeld ermittelt wird, wird Ihnen gefragt, ob Sie fortfahren möchten. Es wird empfohlen, mindestens eine Plattform voranzubringen.

Schritt 2: Hinzufügen Ihres Apps

Der CLI wird Sie in Capgo anmelden und Ihre App Ihrem Account hinzufügen.

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

❓ Add {appId} in Capgo?

Wenn Ihr 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?

Sie können eine Vorschlag auswählen oder eine benutzerdefinierte App-ID eingeben.

Hinweis

App-IDs müssen die umgekehrte Domänennotation (z.B., com.example.myapp)

Schritt 3: Erstellen Sie einen Produktionskanal

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

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

Hinweis

Machen Sie sich keine Sorgen! Dies ist nur für lokale Tests während der Einrichtung gedacht. Das Erstellen eines 'Produktions'-Kanals bedeutet nicht, dass Ihre Updates sofort an Kunden gehen. Sie haben die volle Kontrolle darüber, wann Updates bereitgestellt werden. Wählen Sie 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 Standard gesetzt. 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:

• Den Kanal in Ihrem capacitor.config.ts Datei
• Den JavaScript setChannel() Methode verwenden, um den Kanal dynamisch zu setzen
• Die Kanäle später von der Capgo Webkonsole konfigurieren

Schritt 4: Updater-Plugin installieren

Das CLI installiert das @capgo/capacitor-updater Plugin ist kompatibel mit Ihrer Capacitor Version.

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

Versionenkompatibilität:

• 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 Updates sofort anwenden, wenn sie im Hintergrund läuft und neu gestartet wird. Dies funktioniert reibungslos, weil Capgo Updates weltweit innerhalb von weniger als 300ms verteilen kann. Ohne es (Standardmodus), werden Updates im Hintergrund heruntergeladen und auf dem nächsten App-Neustart angewendet. Sofortige Aktualisierungen sind großartig für eine schnellere Iteration während der Entwicklung und kritische Fehlerbehebungen in der Produktion.

If Sie "Ja" auswählen:

• Updates werden so konfiguriert, dass sie sofort angewendet werden, wenn die App im Hintergrund geschlossen und wieder geöffnet wird
• autoUpdate: 'always' und autoSplashscreen: true werden zu Ihrer Konfiguration hinzugefügt
• Ihr capacitor.config.ts werden automatisch aktualisiert
• Deltabeträge werden automatisch aktiviert - dies sendet nur die Dateien, die zwischen den Updates geändert wurden, anstatt des gesamten Bundles, was die Updates viel schneller macht

If Sie "Nein" auswählen:

• Updates werden standardmäßiges Verhalten anwenden (Hintergrundherunterladen, Anwendung beim nächsten Neustart)
• Sie können Instant-Updates immer noch aktivieren, indem Sie Ihre capacitor.config.ts

Schritt 5: Fügen Sie die Integration Code hinzu

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

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

Was hinzugefügt wird:

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

CapacitorUpdater.notifyAppReady()

Projekttyp-Detektion:

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

Tip

If auto-injection fehlschlägt, Sie können den code manuell in Ihre 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 in Ihre Haupteingangsdatei (z.B. main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Platzieren Sie den code nach Ihren Imports und vor der Initialisierung Ihrer App. Weitere Details finden Sie im Hinzufügen einer App-Leitfaden.

Schritt 6: Verschlüsselung einrichten (Optional)

End-to-end-Verschlüsselung fügt einem zusätzlichen Sicherheitslayer 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 der CLI Folgendes tun:

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

Schritt 7: Plattform auswählen

Wählen Sie während der Einrichtung die Plattform aus, mit der getestet werden soll.

📱 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

Tip

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. Ermittelt den Projekttyp
2. Führt Ihren Build-Skript aus
3. Ausführt npx cap sync {platform}

Wenn Build-Skript fehlt:

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

Schritt 9: Auf 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 wä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: Änderung zum Testen vornehmen

Jetzt ist es Zeit, Capgo's Update-System 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: Der CLI wird Ihre Dateien automatisch ändern, um eine sichtbare Testbanner-Anzeige hinzuzufügen oder zu ändern.

Manueller Modus: Sie machen Ihre eigenen Änderungen (z.B. Text, Farben oder hinzufügen Sie Elemente).

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?

Tip

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: Upload Bundle

Hochladen Sie Ihr aktualisiertes App-Bundle auf Capgo.

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

Der CLI läuft:

npx @capgo/cli@latest bundle upload

Tipp

Delta-Updates mit sofortigen Updates: Wenn Sie in Schritt 4 sofortige Updates aktiviert haben, wird der CLI automatisch fragen, ob Sie Delta-Updates aktivieren möchten. Delta-Updates senden nur die Dateien, die zwischen den Versionen geändert wurden, anstatt das gesamte Bundle. Da normalerweise nur wenige Dateien zwischen den Updates geändert werden, macht dies die Herunterladung viel schneller. Wählen Sie Ja für die beste Erfahrung mit sofortigen Updates.

Delta-Updates lösen (wenn eine 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)

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: Update auf Gerät testen

Zeit, um 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 standardmäßige 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

Protokolle überwachen:

❓ Monitor Capgo logs to verify the update worked?

Wenn Sie "Ja" auswählen Sie sehen live Protokolle von Ihrem Gerät, die den Update-Prozess anzeigen.Schritt 13: Abschluss

Abschnitt mit dem Titel "Schritt 13: Abschluss"

Welcome onboard ✈️!

Herzlichen Glückwunsch! Sie haben Capgo erfolgreich für Ihre App live aktualisiert.

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 ist 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:

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

Für weitere Bereitstellungsoptionen siehe Ein Live-Update bereitstellen.

Wiederaufnahme der Einrichtung

Wenn Sie den 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?

Tipp

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

Fehlersuche

Keine Entwicklungsumgebung

Problem: Kein Xcode- oder Android-SDK-Entdeckungsprozess.

Lösung:

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

Satztitel “App-ID bereits vergeben”

Ihre App-ID ist bereits registriert. Lösung:

__CAPGO_KEEP_0__ Wählen Sie eine der vorgeschlagenen Alternativen oder geben Sie einen benutzerdefinierten App-Id in umgekehrter Domänennotation ein.

Build-Script fehlt

Problem: Kein Build-Script in package.json.

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

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

Auto-Injektion fehlgeschlagen

Problem: CLI kann die Integration code nicht automatisch einfügen.

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

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

CapacitorUpdater.notifyAppReady()

Capacitor Version Zu Alt

Problem: Ihre Capacitor Version liegt unter v5.

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

• Capacitor auf Version 5 updaten
• Capacitor auf Version 6 updaten
• Capacitor auf Version 7 updaten

Weitere Schritte

Jetzt, dass 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 Ihre Update-Deployments 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

Updateverhalten

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

Unterstützung

Wenn Sie während der Einrichtung Probleme auftreten:

• Überprüfen Sie das Troubleshooting-Guide
• Beitreten Sie zur Discord-Gemeinschaft
• Überprüfen Sie die FAQ
• Kontakt Support

Weiter von CLI Onboarding Guide

Wenn Sie __CAPGO_KEEP_0__ Onboarding Guide verwenden CLI Onboarding Guide um das Dashboard und API-Operationen zu planen, verbinden Sie es mit API Overview für die Implementierungsdetails in API Overview Einführung für die Implementierungsdetails in Einführung API Keys für die Implementierungsdetails in API Schlüsseln Geräte für die Implementierungsdetails in Geräten, und Bündel für die Implementierungsdetails in Bündeln.