Capacitor CLI: Guida al setup del progetto

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

Quick Setup: Installa Capacitor CLI e inizializza il tuo progetto in pochi minuti.
Integrazione della piattaforma: Aggiungi il supporto iOS e Android con comandi semplici.
Live Update: Usa Capgo per aggiornamenti over-the-air istantanei.
Risoluzione problemi comuni: Risolvi errori di sync o fallimenti del build.

Passaggi chiave per iniziare:

Installazione 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 gli aggiornamenti app.

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

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 build iOS)
Android Studio (per build Android)
Capacitor CLI (versione 6 o 7)

Opzionale: Se vuoi abilitare i live updates, dai un'occhiata a “Guida al setup di Capgo” qui sotto.

Passaggi per l'installazione di CLI

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

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

Questo comando installa Capacitor e configura i suoi componenti core.

Dopo aver completato questo passaggio, passa a Creazione di un nuovo progetto per generare lo scaffold della tua applicazione.

Creazione di un nuovo progetto

Per iniziare 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 nel tuo progetto.

Setup delle piattaforme

Completata la struttura del progetto, è ora di configurare i target iOS e Android.

Aggiunta di iOS e Android

Inizia installando i pacchetti specifici per la piattaforma tramite Capacitor CLI:

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

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

Una volta installato, dovrai aggiornare i tuoi target nativi con le modifiche apportate alla tua 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

L'oggetto 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

IDE Setup

Apri i progetti specifici della piattaforma negli IDE appropriati:

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

In Xcode:

Seleziona il tuo development team.
Configura i certificati di firma.
Aggiorna il bundle identifier.

In Android Studio:

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

Una volta configurato tutto, builda i progetti con npx cap build ios o npx cap build android. Non dimenticare di eseguire npx cap sync di nuovo per assicurarti che tutti gli asset siano aggiornati.

Capgo Setup Guide

Interfaccia Dashboard Capgo Live Update

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

Caratteristiche principali di Capgo

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

Crittografia end-to-end garantisce la consegna sicura degli aggiornamenti.
Updates run in background all'avvio dell'app.
Gli strumenti di analytics help track update success rates and user engagement.
Un rollback con un click Questa opzione ti permette di recuperare rapidamente da update problematici.
Usa il valore sistema a canali per rollout graduali e beta testing.

Installare Capgo

Segui questi passaggi per iniziare con Capgo:

Installa CLI di Capgo:
```
npm install --save @capgo/cli
```
Inizializza Capgo nel tuo progetto:
```
npx capgo init
```
Build e release degli update:
```
npm run build
npx capgo release
```
Apri l'app per avviare il processo di update 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 e che gli utenti restino attivi.
Enable error tracking to catch and fix issues early.
Tieni pronta la funzione di rollback per gestire rapidamente eventuali criticità.

Capgo è compatibile con Capacitor 8, si integra perfettamente nelle pipeline CI/CD e rispetta i requisiti di Apple e Google Store.

Problemi comuni e consigli

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

Problemi di configurazione dell'ambiente

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

Problemi di configurazione

Mismatch Config Errore: Le modifiche a capacitor.config.json non hanno effetto. Soluzione: Assicurati che i appId e webDir valori corrispondano a quelli del package.json progetto e alla cartella di output del web build.
Errori di sincronizzazione della piattaforma Errore: L'esecuzione di npx cap sync causa conflitti tra le versioni dei plugin. Soluzione: Aggiorna @capacitor/android e @capacitor/ios alla stessa major version, 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.
Web Directory non trovata Errore: npx cap sync non riesce a trovare gli asset web. Soluzione: Esegui il comando di build web (es. npm run build) prima di sincronizzare le piattaforme.

Problemi Live Update

Errori di Capgo Update Errore: Gli update non appaiono nell'app in produzione. Soluzione: Controlla bene il tuo chiave Capgo API in capacitor.config.json e assicurati di puntare al canale corretto.

Per maggiori dettagli sulla configurazione delle piattaforme, consulta la sezione Platform Setup. Se utilizzi le live updates, leggi la Capgo Setup Guide per ulteriori consigli sulla risoluzione dei problemi.

Riassunto

Revisione Setup

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

Ecco come iniziare:

Usa Capacitor CLI per inizializzare il tuo progetto.
Configura 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 o troubleshooting, consulta la documentazione ufficiale di Capacitor e Capgo.

Continua da Capacitor CLI: Project Setup Guide

Se stai usando Capacitor CLI: Project Setup Guide per pianificare dashboard e operazioni API, collegalo a API Panoramica per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli implementativi nell'Introduzione, Chiavi API per i dettagli di implementazione in API Keys, Dispositivi per i dettagli di implementazione in Devices, e Bundle per i dettagli di implementazione nei Bundle.