Checklist di setup iniziale
Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.
Hai completato l'onboarding. Ora configura Capgo una volta. Dopodiché, il lavoro quotidiano è solo upload → test → deploy.
Regola: i canali sono binari di rilascio (development, production), non ticket, feature o nomi di sviluppatori.
Checklist di setup iniziale
Sezione intitolata “Checklist di configurazione iniziale”-
Crea i canali: scegli il set minimo necessario (vedi sotto).
-
Imposta il canale di upload predefinito nella impostazioni app:
- App singola →
production - Team →
development
- App singola →
-
Canale di produzione: public attivo, device self-set disattivato, blocco aggiornamenti sotto native attivo, auto-update guard attivo
major. -
Canale di test (
development/staging): public disattivato, device self-set attivo per QA. -
Upload dalla CI con
--delta(checksum e dipendenze native sono automatici):Finestra del terminale npx @capgo/cli@latest bundle upload \--channel development \--bundle "1.8.0-${BUILD_NUMBER}" \--comment "commit ${GIT_SHA:0:7} run ${CI_RUN_ID}" \--deltaIl
--bundlevalore devi essere valido versionamento semantico. Validalo nel tester SemVer prima di caricare. -
Deploy in produzione solo dopo i test, dal dashboard o CLI.
-
Team e sicurezza: invita una volta sola, con i permessi minimi, 2FA per l'org, una chiave API in CI.
Lascia la crittografia, min_update_version, i metadati e l'anteprima off a meno che tu non abbia un motivo valido.
Scegli la dimensione
Sezione intitolata “Scegli la tua dimensione”Semplice: 1 app, 1 canale: production
Team: development + production. Upload su dev, deploy su prod.
Versioni native: aggiungi canali solo se necessario, ad es. production-9.0 + test-9.0. Mantieni gli utenti dello store sul canale di produzione principale.
Molte app: lo stesso semplice modello per app (di solito uno production per ciascuna). Non creare canali extra solo perché l'organizzazione è grande.
Treno di rilascio (opzionale): staging → rc → production. Lo stesso template su ogni app che ne ha bisogno.
Nome del bundle vs commento
Sezione intitolata “Bundle name vs comment”I nomi dei bundle sono obbligatorio da seguire versionamento semantico. Capgo usa semver per i controlli di compatibilità, le regole di auto-aggiornamento dei canali e i rollback. Verifica ogni nome in tester SemVer prima dell'upload.
- Nome = semver da CI, ad es.
1.8.0,1.8.0-beta.1, o1.8.0-20260629.42 - Commento = testo libero per gli umani →
commit abc1234 run 28059070270
Usa semver pre-release etichette (la parte dopo -) quando pubblichi molti build sotto lo stesso MAJOR.MINOR.PATCH. Ad esempio, mantieni 1.8.0 e aggiungi la data o il contatore di build nella pre-release: 1.8.0-20260629.1, 1.8.0-beta.2. Non inventare formati personalizzati come fix-login-bug oppure 2.5.2026062306. Non sono semver validi e gli upload falliranno o si comporteranno in modo imprevedibile.
Metti le note di rilascio in --comment, non nel nome del bundle.
Vedi anche targeting delle versioni e versioning dei bundle.
Upload delta
Sezione intitolata “Delta upload”--delta upload file delta in modo che i dispositivi scarichino solo i file modificati invece dell'intero bundle ogni volta. Il checksum viene sempre calcolato automaticamente. Non è necessario passare un flag checksum.
Predefinito: --delta (file delta + backup zip)
Sezione intitolata “Default: --delta (file delta + backup zip)”npx @capgo/cli@latest bundle upload \ --channel development \ --bundle "1.8.0-${BUILD_NUMBER}" \ --deltaQuesta è l'impostazione predefinita consigliata per la maggior parte delle app. Capgo memorizza i file delta e e mantiene lo zip completo come backup. I dispositivi con una versione vecchia del plugin senza supporto Delta utilizzano lo zip. Ideale quando il costo dello storage non è la tua priorità.
Risparmio di spazio: --delta-only
Sezione intitolata “Risparmio di storage: --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-onlyUsa --delta-only when you want to ridurre lo storage di Capgo. Vengono salvati solo i file delta, non lo zip completo. Scegli questa opzione per app grandi o volumi di upload elevati, dove lo storage si accumula.
Trade-off: senza il backup zip sul server, dipendi completamente dai file delta, e i dispositivi con una vecchia versione del plugin senza supporto Delta non possono aggiornarsi. Salta --delta-only a meno che tu non abbia davvero bisogno di risparmiare storage.
Non serve una configurazione extra del plugin sul dispositivo. L'updater legge l'elenco dei file delta e recupera solo i file modificati.
Workflow quotidiano
Sezione intitolata “Workflow giornaliero”Upload to development (--delta) → test → deploy to production → don't touch channel settings againErrori comuni
Sezione intitolata “Errori comuni”| Errore | Soluzione |
|---|---|
| Aspettarsi l'OTA prima di un nuovo rilascio sullo store | Ricostruire e pubblicare l'app nativa dopo aver aggiunto il plugin |
| Caricare un bundle ma non deployarlo su un canale | Assegna il bundle a un canale (es. production) |
| Canale per feature, ticket o sviluppatore | Usa solo lane di rilascio permanenti |
| Nomi di canale CI dinamici | Nomi fissi: development, production |
| Troppi canali per un'app semplice | Inizia con 1-2 canali |
| Impostazione automatica del dispositivo in produzione | Disattivato per la produzione, attivato per i canali di test |
Saltando --delta | Aggiungi --delta ai caricamenti; usa --delta-only solo quando devi risparmiare spazio |
| Nomi di bundle non semver | Segui versionamento semantico e validare nel tester SemVer |
| Cambiare lo schema di versioning nel tempo | Mantieni semver; usa etichette pre-release per build aggiuntive (1.8.0-20260629.1) |
| Metadata / preview abilitati senza motivo | Lascia disabilitato di default |
| Messaggio “Nuova versione disponibile” su un'installazione pulita | Saltalo quando current() restituisce bundle.id === "builtin" (vedi sotto) |
Revisione App Store: nessun messaggio di aggiornamento su installazione pulita
Sezione intitolata “Revisione App Store: nessun messaggio di aggiornamento in un'installazione nuova”Apple accetta le app che utilizzano Capgo. I revisori rifiutano però l'interfaccia circostante: un messaggio “nuova versione disponibile” o “aggiornamento in corso” mostrato al primo avvio.
Questo riguarda principalmente le configurazioni self-hosted e manuali, in cui l'app esegue il proprio controllo versione e mostra il proprio prompt.
Il revisore installa il binario del tuo store. È più vecchio del tuo ultimo bundle, quindi il primo check trova subito un bundle: la tua chiamata al server lo restituisce, oppure l'updater lo trova ed emette updateAvailable. Se la tua app mostra un messaggio in quel momento, il revisore lo vedrà.
Subito dopo una nuova installazione o un aggiornamento nativo dallo store, l'app esegue il bundle incluso e current() restituisce bundle.id === "builtin". In quel caso, salta il tuo messaggio:
import { CapacitorUpdater } from '@capgo/capacitor-updater'
const { bundle } = await CapacitorUpdater.current()if (bundle.id !== 'builtin') { showNewVersionMessage()}In qualsiasi UI visibile, evita le parole “update”, “live update”, “OTA”, “downloading” e “installing”. Vedi conformità.