Vai al contenuto

Checklist di setup iniziale

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.


  1. Crea i canali: scegli il set minimo necessario (vedi sotto).

  2. Imposta il canale di upload predefinito nella impostazioni app:

    • App singola → production
    • Team → development
  3. Canale di produzione: public attivo, device self-set disattivato, blocco aggiornamenti sotto native attivo, auto-update guard attivo major.

  4. Canale di test (development / staging): public disattivato, device self-set attivo per QA.

  5. 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}" \
    --delta

    Il --bundle valore devi essere valido versionamento semantico. Validalo nel tester SemVer prima di caricare.

  6. Deploy in produzione solo dopo i test, dal dashboard o CLI.

  7. 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.


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.


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, o 1.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.


--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)”
Finestra del terminale
npx @capgo/cli@latest bundle upload \
--channel development \
--bundle "1.8.0-${BUILD_NUMBER}" \
--delta

Questa è 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à.

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}" \
--delta-only

Usa --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.


Upload to development (--delta)
→ test
→ deploy to production
→ don't touch channel settings again

ErroreSoluzione
Aspettarsi l'OTA prima di un nuovo rilascio sullo storeRicostruire e pubblicare l'app nativa dopo aver aggiunto il plugin
Caricare un bundle ma non deployarlo su un canaleAssegna il bundle a un canale (es. production)
Canale per feature, ticket o sviluppatoreUsa solo lane di rilascio permanenti
Nomi di canale CI dinamiciNomi fissi: development, production
Troppi canali per un'app sempliceInizia con 1-2 canali
Impostazione automatica del dispositivo in produzioneDisattivato per la produzione, attivato per i canali di test
Saltando --deltaAggiungi --delta ai caricamenti; usa --delta-only solo quando devi risparmiare spazio
Nomi di bundle non semverSegui versionamento semantico e validare nel tester SemVer
Cambiare lo schema di versioning nel tempoMantieni semver; usa etichette pre-release per build aggiuntive (1.8.0-20260629.1)
Metadata / preview abilitati senza motivoLascia disabilitato di default
Messaggio “Nuova versione disponibile” su un'installazione pulitaSaltalo 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à.