Checkliste für die Ersteinrichtung
Kopiere einen Setup-Prompt mit den Installationsschritten und dem vollständigen Markdown-Guide für dieses Plugin.
Du hast das Onboardingbeendet. Jetzt konfiguriere Capgo einmal. Danach sieht dein Workflow nur noch so aus: upload → testen → deployen.
Regel: Channels sind Release-Lanes (development, production), keine Tickets, Features oder Entwicklernamen.
Checkliste für die Ersteinrichtung
Section titled “One time setup checklist”-
Channels erstellen: wähle die kleinste passende Menge (siehe unten).
-
Standard-Upload-Channel festlegen in einem App-Einstellungen:
- Solo-App →
production - Team →
development
- Solo-App →
-
Production-Channel: public an, device self-set aus, block updates under native an, auto-update guard an
major. -
Test-Channel (
development/staging): public aus, device self-set an für QA. -
Upload via CI mit
--delta(Checksummen und Native Build-Abhängigkeiten erfolgen automatisch):Terminalfenster npx @capgo/cli@latest bundle upload \--channel development \--bundle "1.8.0-${BUILD_NUMBER}" \--comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \--deltaDer
--bundleWert musst muss gültig sein Semantic Versioning. Validierung im SemVer-Tester bevor du hochlädst. -
In Produktion deployen erst nach dem Testen, über das Dashboard oder CLI.
-
Team & Sicherheit: einmal einladen, minimale Rechte, 2FA für die Org, ein API Key in der CI.
Verschlüsselung, min_update_version, Metadaten und Preview aus außer du hast einen triftigen Grund.
Wähle deine Größe
Abschnitt mit dem Titel „Wähle deine Größe“Einfach: 1 App, 1 Channel: production
Team: development + production. Upload auf dev, Deploy auf prod.
Native Versionen: füge Channels nur bei Bedarf hinzu, z. B. production-9.0 + test-9.0. Halte Store-User auf dem Haupt-Production-Channel.
Viele Apps: das gleiche einfache Modell pro App (meistens ein production jedem). Erstelle keine extra Channels, nur weil die Orga groß ist.
Release-Train (optional): staging → rc → production. Dasselbe Template für jede App, die es benötigt.
Bundle-Name vs. Kommentar
Abschnitt mit dem Titel „Bundle-Name vs. Kommentar“Bundle-Namen sind erforderlich zu befolgen Semantic Versioning. Capgo nutzt SemVer für Kompatibilitätsprüfungen, Channel-Auto-Update-Regeln und Rollbacks. Validiere jeden Namen in der SemVer-Tester vor dem Upload.
- Name = SemVer aus der CI, z. B.
1.8.0,1.8.0-beta.1, oder1.8.0-20260629.42 - Kommentar = Freitext für Menschen →
commit abc1234 run 28059070270
Nutze SemVer Pre-release Labels (der Teil nach -) wenn du viele Builds unter derselben MAJOR.MINOR.PATCH. Beispielsweise solltest du 1.8.0 und das Datum oder einen Build-Counter in der Pre-Release-Version hinzufügen: 1.8.0-20260629.1, 1.8.0-beta.2. Erfinde keine eigenen Formate wie fix-login-bug oder 2.5.2026062306. Diese entsprechen nicht dem Semver-Standard; Uploads schlagen fehl oder verhalten sich unvorhersehbar.
Schreibe Release Notes in --comment, nicht in den Bundle-Namen.
Siehe auch Version-Targeting und Bundle-Versioning.
Delta-Upload
Abschnitt mit dem Titel „Delta-Upload“--delta Uploads Delta-Dateien Damit laden Geräte nur geänderte Dateien statt jedes Mal das gesamte Bundle herunter. Der Checksum wird immer automatisch berechnet. Du musst kein Checksum-Flag übergeben.
Standard: --delta (Delta-Dateien + ZIP-Backup)
Abschnitt mit dem Titel „Standard: --delta (Delta-Dateien + ZIP-Backup)“npx @capgo/cli@latest bundle upload \ --channel development \ --bundle "1.8.0-${BUILD_NUMBER}" \ --deltaDies ist die empfohlene Standardeinstellung für die meisten Apps. Capgo speichert die Delta-Dateien und behält die vollständige ZIP-Datei als Backup. Geräte mit einer alten Plugin-Version ohne Delta-Support nutzen die ZIP. Gut geeignet, wenn Speicherkosten keine Priorität haben.
Speicherplatz sparen: --delta-only
Abschnitt „Speicherplatz sparen: --delta-only“npx @capgo/cli@latest bundle upload \ --channel development \ --bundle "1.8.0-${BUILD_NUMBER}" \ --comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \ --delta-onlyNutzt --delta-only wenn du möchtest den Speicherplatz von Capgo reduzierenmöchtest. Es werden nur die Delta-Dateien gespeichert, nicht das komplette ZIP. Wähle das für große Apps oder hohes Upload-Volumen, wo sich der Speicherplatz summiert.
Trade-off: Ohne das ZIP-Backup auf dem Server bist du voll auf Delta-Dateien angewiesen, und Geräte mit einer alten Plugin-Version ohne Delta-Support können nicht updaten. Überspringe das, --delta-only es sei denn, du brauchst die Speicherersparnis wirklich.
Auf dem Gerät ist keine zusätzliche Plugin-Konfiguration nötig. Der Updater liest die Liste der Delta-Dateien und lädt nur die geänderten Dateien herunter.
Täglicher Workflow
Abschnitt mit dem Titel „Täglicher Workflow“Upload to development (--delta) → test → deploy to production → don't touch channel settings againHäufige Fehler
Abschnitt mit dem Titel „Häufige Fehler“| Fehler | Lösung |
|---|---|
| OTA vor einem neuen Store-Release erwarten | Native App nach dem Hinzufügen des Plugins neu bauen und ausliefern |
| Bundle hochladen, aber nicht auf einen Channel deployen | Bundle einem Channel zuweisen (z. B. production) |
| Channel pro Feature, Ticket oder Developer | Nur permanente Release-Lanes nutzen |
| Dynamische CI-Channelnamen | Feste Namen: development, production |
| Zu viele Channels für eine einfache App | Mit 1–2 Channels starten |
| Gerät setzt sich in Production selbst | In Produktion aus, für Test-Channels an |
Überspringen --delta | Füge --delta für Uploads; nutze --delta-only nur, wenn du Speicherplatz sparen willst |
| Nicht-SemVer Bundle-Namen | Folgen Semantic Versioning und validieren im SemVer Tester |
| Versioning-Schema über die Zeit ändern | SemVer beibehalten; Pre-release-Labels für Extra-Builds nutzen (1.8.0-20260629.1) |
| Metadaten / Vorschau ohne Grund aktiviert | Standardmäßig deaktiviert |
| „Neue Version verfügbar“-Meldung bei Neuinstallation | Überspringen, wenn current() gibt zurück bundle.id === "builtin" (siehe unten) |
App Store Review: Keine Update-Meldung bei Neuinstallation
Abschnitt „App Store Review: Keine Update-Meldung bei einer Neuinstallation“Apple akzeptiert Apps, die Capgo nutzen. Die Reviewer lehnen jedoch das UI darum ab: eine „Neue Version verfügbar“- oder „Update läuft“-Meldung beim ersten Start.
Dies betrifft meist Self-Hosted- oder manuelle Setups, bei denen deine App einen eigenen Version-Check durchführt und einen eigenen Prompt anzeigt.
Der Reviewer installiert dein Store-Binary. Da es älter als dein letztes Bundle ist, findet der erste Check sofort ein Bundle: Dein eigener Server-Call liefert es zurück, oder der Updater findet es und gibt aus updateAvailable. Wenn deine App dann eine Meldung anzeigt, sieht der Reviewer diese.
Direkt nach einer Neuinstallation oder einem Native Store Update führt die App das bereitgestellte Bundle aus und current() gibt zurück bundle.id === "builtin". Überspringe deine Nachricht in diesem Fall:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
const { bundle } = await CapacitorUpdater.current()if (bundle.id !== 'builtin') { showNewVersionMessage()}Vermeide in der UI Begriffe wie „Update“, „live update“, „OTA“, „downloading“ oder „installing“. Siehe Compliance.