Checklist di setup iniziale

Copia un prompt di configurazione con i passaggi di installazione e la guida markdown completa per questo plugin.

Hai finito onboarding. Ora configura Capgo una volta. Da quel momento, il lavoro quotidiano sarà solo upload → test → deploy.

Regola: i canali sono lane di rilascio (development, production), non ticket, feature o nomi di developer.

Checklist di setup iniziale

Crea i canali: scegli il set minimo necessario (vedi sotto).
Imposta il canale di upload predefinito in impostazioni app:
- Solo app → production
- Team → development
Canale di produzione: public on, device self-set off, block updates under native on, auto-update guard on major.
Canale di test (development / staging): public off, device self-set on per QA.
Upload dalla CI con --delta (checksum e dipendenze native automatiche):
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 deve essere valido versionamento semantico. Validalo nel Tester SemVer prima dell'upload.
Deploy in produzione solo dopo i test, dalla dashboard o CLI.
Team e sicurezza: invita una volta, permessi minimi, 2FA per l'org, un tasto API in CI.

Lascia la crittografia, min_update_version, i metadati e l'anteprima disattivati a meno di esigenze specifiche.

Scegli la dimensione

Semplice: 1 app, 1 canale: production

Team: development + production. Upload su dev, deploy su prod.

Versioni Native: aggiungi canali solo se necessario, es. production-9.0 + test-9.0. Mantieni gli utenti dello store sul canale di produzione principale.

Molte app: stesso modello semplice per app (solitamente uno production per ciascuna). Non creare canali extra solo perché l'org è grande.

Release train (opzionale): staging → rc → production. Stesso template per ogni app che ne ha bisogno.

Nome bundle vs commento

I nomi dei bundle devono required seguire il versionamento semantico. Capgo usa il semver per i controlli di compatibilità, le regole di auto-update dei canali e i rollback. Valida ogni nome nel Tester SemVer prima dell'upload.

Nome = semver dalla CI, 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 labels (la parte dopo -) quando rilasci molti build con 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 o 2.5.2026062306. Non sono semver validi e l'upload fallirà o si comporterà in modo imprevedibile.

Inserisci le release notes in --comment, non nel nome del bundle.

Vedi anche target delle versioni e versionamento dei bundle.

Upload delta

--delta upload file delta così i dispositivi scaricano solo i file modificati invece dell'intero bundle ogni volta. Il checksum viene calcolato automaticamente. Non è necessario passare un flag per il checksum.

Predefinito: `--delta` (file delta + backup zip)

npx @capgo/cli@latest bundle upload \
  --channel development \
  --bundle "1.8.0-${BUILD_NUMBER}" \
  --delta

Questo è il default consigliato per la maggior parte delle app. Capgo memorizza i file delta e mantiene il file zip completo come backup. I dispositivi con una vecchia versione del plugin senza supporto Delta useranno lo zip. Ideale se i costi di storage non sono la priorità.

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-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 pesanti o alti volumi di upload dove lo storage incide molto.

Trade-off: senza il backup zip sul server, dipendi totalmente dai file delta; i dispositivi con vecchie versioni dei plugin senza supporto Delta non potranno 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 la lista dei file delta e scarica solo quelli modificati.

Workflow quotidiano

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

Errori comuni

Errore	Soluzione
Aspettarsi l'OTA prima di un nuovo rilascio sugli store	Ricompila e rilascia l'app nativa dopo l'aggiunta del plugin
Caricamento di un bundle senza deploy su un channel	Assegna il bundle a un channel (es. `production`)
Channel per feature, ticket o developer	Usa solo release lane permanenti
Nomi dei channel dinamici in CI	Nomi fissi: `development`, `production`
Troppi channel per un'app semplice	Inizia con 1-2 channel
Impostazione automatica del device in produzione	Disattivato in produzione, attivo per i channel di test
Salta `--delta`	Aggiungi `--delta` per gli upload; usa `--delta-only` solo se devi risparmiare spazio
Nomi bundle non-semver	Segui il semantic versioning e valida con il Tester SemVer
Cambiare lo schema di versioning nel tempo	Mantieni semver; usa label pre-release per build extra (`1.8.0-20260629.1`)
Metadata / preview attivati senza motivo	Disattiva di default

Scopri di più

Canali Default, precedenza e routing.

Aggiornamenti delta Perché e come usare --delta.

CI/CD Automatizza upload e deploy.

Bundle Checksum, dipendenze e metadati.

Checklist di setup iniziale