Vai al contenuto
Capgo

Guida Introduttiva

Installazione

Section titled “Installazione”
Terminal window
npm install @capgo/capacitor-updater
npx cap sync

Avvio Rapido

Section titled “Avvio Rapido”

Per la maggior parte degli utenti, consigliamo di seguire la guida Quickstart principale che copre sia l’installazione del plugin che l’integrazione con Capgo cloud.

Questa guida introduttiva si concentra sui dettagli tecnici del plugin per utenti avanzati che vogliono comprendere i meccanismi sottostanti o implementare aggiornamenti self-hosted.

Panoramica

Section titled “Panoramica”

Il plugin Capacitor Updater consente aggiornamenti over-the-air (OTA) per le tue applicazioni Capacitor. Questo ti permette di inviare aggiornamenti alla tua app senza passare attraverso le revisioni degli app store.

Come Funziona

Section titled “Come Funziona”
  1. Download del Bundle: Il plugin scarica i bundle di aggiornamento (file ZIP contenenti le tue risorse web)
  2. Estrazione: I bundle vengono estratti nella memoria del dispositivo
  3. Hot Reload: L’app passa al nuovo bundle senza richiedere un riavvio
  4. Fallback: Se un aggiornamento fallisce, l’app torna alla versione precedente funzionante

Modalità di Utilizzo

Section titled “Modalità di Utilizzo”

1. Modalità Auto-Update (Consigliata)

Section titled “1. Modalità Auto-Update (Consigliata)”

Il modo più semplice per utilizzare il plugin con gestione automatica degli aggiornamenti:

import { CapacitorUpdater } from '@capgo/capacitor-updater';


// Il plugin gestisce tutto automaticamente
// Configura in capacitor.config.ts

Aggiungi al tuo capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. Modalità Manuale

Section titled “2. Modalità Manuale”

Per un controllo avanzato sul processo di aggiornamento:

import { CapacitorUpdater } from '@capgo/capacitor-updater';


// Scarica un aggiornamento
const bundle = await CapacitorUpdater.download({
  url: 'https://your-server.com/updates/v1.0.1.zip',
  version: '1.0.1'
});


// Imposta il bundle (verrà usato al prossimo avvio dell'app)
await CapacitorUpdater.set({
  id: bundle.id
});


// Oppure ricarica immediatamente
await CapacitorUpdater.reload();

Configurazione della Piattaforma

Section titled “Configurazione della Piattaforma”

iOS

Section titled “iOS”

Nessuna configurazione aggiuntiva richiesta. Il plugin funziona out of the box.

Android

Section titled “Android”

Nessuna configurazione aggiuntiva richiesta. Il plugin funziona out of the box.

Utilizzo di Base dell’API

Section titled “Utilizzo di Base dell’API”

Scaricare un Aggiornamento

Section titled “Scaricare un Aggiornamento”
import { CapacitorUpdater } from '@capgo/capacitor-updater';


const bundle = await CapacitorUpdater.download({
  url: 'https://example.com/update.zip',
  version: '1.0.1'
});


console.log('Bundle scaricato:', bundle.id);

Impostare il Bundle Attivo

Section titled “Impostare il Bundle Attivo”
// Imposta il bundle da utilizzare al prossimo avvio dell'app
await CapacitorUpdater.set({
  id: bundle.id
});

Ricaricare con Nuovo Bundle

Section titled “Ricaricare con Nuovo Bundle”
// Ricarica l'app immediatamente con il nuovo bundle
await CapacitorUpdater.reload();

Elencare i Bundle

Section titled “Elencare i Bundle”
const { bundles } = await CapacitorUpdater.list();
console.log('Bundle disponibili:', bundles);

Eliminare un Bundle

Section titled “Eliminare un Bundle”
await CapacitorUpdater.delete({
  id: 'bundle-id'
});

Ottenere il Bundle Corrente

Section titled “Ottenere il Bundle Corrente”
const { bundle } = await CapacitorUpdater.current();
console.log('Bundle corrente:', bundle.version);

Event Listeners

Section titled “Event Listeners”

Ascolta gli eventi di aggiornamento:

import { CapacitorUpdater } from '@capgo/capacitor-updater';


// Ascolta il progresso del download
CapacitorUpdater.addListener('download', (info) => {
  console.log('Progresso download:', info.percent);
});


// Ascolta il completamento del download
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Download completato:', bundle.version);
});


// Ascolta gli errori di aggiornamento
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Aggiornamento fallito:', error);
});


// Ascolta gli aggiornamenti riusciti
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Aggiornamento disponibile:', info.version);
});

Opzioni di Configurazione

Section titled “Opzioni di Configurazione”

Configura il plugin nel tuo capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      // Impostazioni auto-update
      autoUpdate: true,
      updateUrl: 'https://api.example.com/updates',


      // Comportamento di aggiornamento
      resetWhenUpdate: true,
      directUpdate: false,


      // Impostazioni versione
      version: '1.0.0',


      // Sicurezza
      allowModifyUrl: false,


      // Raccolta statistiche
      statsUrl: 'https://api.example.com/stats',


      // Channel (per Capgo cloud)
      defaultChannel: 'production'
    }
  }
}

Pattern di Integrazione

Section titled “Pattern di Integrazione”

Con Capgo Cloud

Section titled “Con Capgo Cloud”

Il modo più semplice per iniziare:

// Installa la CLI Capgo
npm install -g @capgo/cli


// Login a Capgo
npx @capgo/cli login


// Carica il tuo primo bundle
npx @capgo/cli bundle upload


// Il plugin si aggiorna automaticamente da Capgo cloud

Vedi la guida Quickstart principale per i dettagli.

Aggiornamenti Self-Hosted

Section titled “Aggiornamenti Self-Hosted”

Ospita il tuo server di aggiornamento:

// Configura il tuo endpoint di aggiornamento
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

Il tuo server dovrebbe rispondere:

{
  "version": "1.0.1",
  "url": "https://your-server.com/updates/1.0.1.zip"
}

Vedi Modalità Self-Hosted per i dettagli completi.

Flusso di Aggiornamento Manuale

Section titled “Flusso di Aggiornamento Manuale”

Controllo completo sugli aggiornamenti:

import { CapacitorUpdater } from '@capgo/capacitor-updater';


async function checkAndUpdate() {
  // Controlla gli aggiornamenti dal tuo server
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();


  // Scarica l'aggiornamento
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });


  // Notifica che il bundle è pronto
  await CapacitorUpdater.notifyAppReady();


  // Imposta come prossima versione
  await CapacitorUpdater.set({ id: bundle.id });


  // Ricarica quando pronto
  await CapacitorUpdater.reload();
}

Migliori Pratiche

Section titled “Migliori Pratiche”
  • Chiama sempre notifyAppReady() quando la tua app si carica con successo
  • Testa accuratamente gli aggiornamenti prima di inviarli in produzione
  • Implementa una corretta gestione degli errori per i fallimenti di rete
  • Usa i numeri di versione in modo coerente
  • Mantieni piccole le dimensioni dei bundle per download più veloci
  • Monitora i tassi di successo degli aggiornamenti

Prossimi Passi

Section titled “Prossimi Passi”

Supporto

Section titled “Supporto”