Guida al setup del progetto Capacitor CLI

Vuoi creare app iOS e Android con un'unica codebase? Capacitor CLI semplifica il processo, permettendoti di creare app native con tecnologie web. Ecco cosa imparerai:

Setup rapido: Installa Capacitor CLI e inizializza il tuo progetto in pochi minuti.
Integrazione delle piattaforme: Aggiungi il supporto per iOS e Android con comandi semplici.
Live Update: Usa Capgo per aggiornamenti over-the-air istantanei.
Correzioni comuni: Risolvi problemi come errori di sync o build fallite.

Passaggi chiave per iniziare:

Installa Node.js, npm, JDK, Xcode, e Android Studio.
Esegui npm install @capacitor/core @capacitor/cli e inizializza il tuo progetto.
Aggiungi le piattaforme iOS e Android usando npx cap add ios e npx cap add android.
Opzionale: configura Capgo per live app più veloci.

Questa guida copre tutto ciò che serve per configurare Capacitor CLI, impostare le piattaforme e distribuire la tua app. Iniziamo!

Ti presentiamo Capacitor Configura

Sito della documentazione del framework Capacitor

Requisiti di configurazione

Per iniziare, assicurati di avere installato i seguenti strumenti:

Node.js (versione 14 o superiore) e npm
JDK Java (versione 11 o superiore)
Xcode (versione 12 o superiore per le build iOS)
Android Studio (per le build Android)
Capacitor CLI (versione 6 o 7)

Facoltativo: Se vuoi abilitare gli aggiornamenti live, consulta la sezione “Guida alla configurazione di Capgo” qui sotto.

Passaggi per l'installazione di CLI

Prima di iniziare, assicurati di avere Node.js, npm, JDK, Xcode, e Android Studio configurati. Una volta pronti, puoi installare Capacitor CLI eseguendo:

npm install --save @capacitor/core @capacitor/cli
npx cap init

Questo comando installa Capacitor e configura i suoi componenti principali.

Dopo aver completato questo passaggio, passa a Creazione di un nuovo progetto per creare la struttura della tua applicazione.

Creazione di un nuovo progetto

Per iniziare con il tuo progetto usando Capacitor CLI, segui questi passaggi:

mkdir my-app && cd my-app
npm init -y
npx cap init my-app com.company.app --web-dir dist

Aggiornamento del file di configurazione

Modifica il capacitor.config.json file per includere le seguenti impostazioni:

{
  "appId": "com.company.app",
  "appName": "My App",
  "webDir": "dist",
  "bundledWebRuntime": false,
  "server": {
    "hostname": "app.example.com",
    "androidScheme": "https"
  }
}

Una volta aggiornato, usa questa configurazione per impostare Capacitor per il tuo progetto.

Configurazione delle piattaforme

Ora che lo scaffolding del progetto è completato, è il momento di configurare i target iOS e Android.

Aggiunta di iOS e Android

Inizia installando i pacchetti specifici per la piattaforma necessari usando Capacitor CLI:

npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

Per iOS, assicurati di avere Xcode 14 o successivo, CocoaPods 1.11 o superiore e macOS 12 o superiore. Per Android, serve Android Studio Giraffe (2022.3.1+), JDK 17 o superiore e Gradle 7.5 o superiore.

Una volta installato, dovrai mantenere aggiornati i tuoi target nativi con le modifiche alla web app.

Aggiornamenti delle piattaforme

Per sincronizzare le piattaforme con le ultime modifiche web, segui questi passaggi dopo aver aggiornato la tua web app:

npm run build
npx cap sync

Il cap sync il comando gestisce due task:

Copia gli asset web aggiornati sulle piattaforme native
Aggiorna le configurazioni native e i plugin per riflettere le ultime modifiche

Setup IDE

Apri i progetti specifici per piattaforma negli IDE appropriati:

npx cap open ios     # Opens Xcode
npx cap open android # Opens Android Studio

In Xcode:

Scegli il tuo team di sviluppo.
Configura i certificati di firma.
Aggiorna il tuo bundle identifier.

In Android Studio:

Modifica l'application ID in build.gradle.
Configura il keystore per la firma.
Configura sia le varianti di build debug che release.

Quando tutto è configurato, compila i progetti usando npx cap build ios oppure npx cap build android. Non dimenticare di eseguire npx cap sync di nuovo per assicurarti che tutte le risorse siano aggiornate.

Capgo Setup Guide

Capgo Live Update Interfaccia Dashboard

Configura Capgo per abilitare aggiornamenti over-the-air istantanei per la tua app.

Funzionalità chiave di Capgo

Capgo offre diversi strumenti per semplificare gli aggiornamenti dell'app:

Crittografia end-to-end garantisce la consegna sicura degli aggiornamenti.
Updates run in background all'avvio dell'app.
Strumenti di analytics per monitorare i tassi di successo degli update e l'engagement degli utenti.
Un rollback con un click consente di recuperare rapidamente da update problematici.
Usa il sistema di canali per rollouts graduali e test beta.

Installazione di Capgo

Segui questi passaggi per iniziare con Capgo:

Installa Capgo CLI:
```
npm install --save @capgo/cli
```
Inizializza Capgo nel tuo progetto:
```
npx capgo init
```
Crea e pubblica gli aggiornamenti:
```
npm run build
npx capgo release
```
Apri l'app per avviare il processo di aggiornamento in background.

Best practice

Usa i canali per testare gli update prima di rilasciarli a tutti gli utenti.
Monitora le analytics per assicurarti che gli update vengano consegnati correttamente e che gli utenti restino coinvolti.
Enable error tracking to catch and fix issues early.
Tieni pronta la funzione di rollback per risolvere rapidamente eventuali problemi.

Capgo è compatibile con Capacitor 8, si integra senza problemi nelle pipeline CI/CD e rispetta i requisiti degli store Apple e Google.

Problemi comuni e consigli

Una volta completata la configurazione della piattaforma e di Capgo, potresti incontrare alcuni errori comuni. Ecco come risolverli velocemente.

Problemi di configurazione dell'ambiente

CLI non trovato Errore: Il comando npx cap fallisce. Soluzione: Esegui npm install --save @capacitor/cli @capacitor/core e riprova.
Versione Node non corrispondente Errore: i comandi CLI falliscono a causa di errori di versione di Node.js. Soluzione: Installa Node.js versione 14 o superiore, come indicato nei requisiti di setup.

Problemi di configurazione

Configurazione non corrispondente Errore: le modifiche a capacitor.config.json non vengono applicate. Soluzione: assicurati che i appId e webDir i valori corrispondono al tuo progetto package.json e alla cartella di output del build web.
Errori di sincronizzazione piattaforma Errore: in esecuzione npx cap sync causa conflitti di versione dei plugin. Soluzione: Aggiorna @capacitor/android e @capacitor/ios alla stessa versione major, quindi riesegui il comando sync.

Build e deployment

Errori di firma della build Errore: Le build iOS o Android falliscono per certificati o keystore mancanti. Soluzione: Segui le istruzioni di setup dell'IDE. Per iOS, aggiungi il tuo team di sviluppo in Xcode. Per Android, configura il keystore in build.gradle.
Directory web non trovata Errore: npx cap sync non riesce a trovare gli asset web. Soluzione: Esegui il comando di build web (ad es., npm run build) prima di sincronizzare le piattaforme.

Problemi con Live Update

Fallimenti di Capgo Errore: Gli aggiornamenti non vengono visualizzati nell'app di produzione. Soluzione: Verifica attentamente il tuo chiave Capgo API nella capacitor.config.json e assicurati di puntare al canale corretto.

Per maggiori dettagli sulla configurazione specifica della piattaforma, rivedi la sezione Platform Setup. Se stai lavorando con live updates, consulta la Capgo Setup Guide per suggerimenti aggiuntivi di troubleshooting.

Riassunto

Revisione setup

Avvia la tua web app con Capacitor CLI, configura le piattaforme iOS e Android e, facoltativamente, includi Capgo per le live updates.

Ecco come iniziare:

Usa Capacitor CLI per inizializzare il tuo progetto.
Imposta il package ID della tua app e definisci la directory di output web.
Aggiungi il supporto per le piattaforme iOS e Android.
Installa e configura Capgo con il seguente comando: npm install --save @capgo/cli && npx capgo init

Per istruzioni dettagliate di configurazione o risoluzione dei problemi, consulta la documentazione ufficiale di Capacitor e Capgo.

Riprendi da Capacitor CLI: Guida al setup del progetto

Se stai usando Guida al setup del progetto Capacitor CLI per pianificare le operazioni della dashboard e di API, collegalo a Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione delle chiavi API, Dispositivi per i dettagli di implementazione in Devices, e Bundle per il dettaglio di implementazione in Bundles.