Per iniziare

Installazione

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Poi usa il seguente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-updater` plugin in my project.

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

npm

bun add @capgo/capacitor-updater
bunx cap sync

yarn

yarn add @capgo/capacitor-updater
bunx cap sync

pnpm

pnpm add @capgo/capacitor-updater
bunx cap sync

bun

bun add @capgo/capacitor-updater
bunx cap sync

Guida rapida

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

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

Panoramica

Il plugin Capacitor Updater abilita gli aggiornamenti over-the-air (OTA) per le tue applicazioni Capacitor. Potrai così rilasciare aggiornamenti senza passare per le revisioni degli app store.

Come funziona

1. Download bundle: Il plugin scarica i bundle di aggiornamento (file ZIP contenenti i tuoi web asset)
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

Usage Modes

1. Modalità auto-update (consigliata)

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

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

// Plugin handles everything automatically
// Configure in capacitor.config.ts

Aggiungi al tuo capacitor.config.ts:

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

2. Modalità manuale

Per un controllo avanzato sul processo di update:

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

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

// Set the bundle (will be used on next app start)
await CapacitorUpdater.set({
  id: bundle.id
});

// Or reload immediately
await CapacitorUpdater.reload();

Configurazione della piattaforma

iOS

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

Android

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

Uso base di API

Scarica 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('Downloaded bundle:', bundle.id);

Imposta il bundle attivo

// Set bundle to be used on next app start
await CapacitorUpdater.set({
  id: bundle.id
});

Ricarica con il nuovo bundle

// Reload app immediately with new bundle
await CapacitorUpdater.reload();

Elenco bundle

const { bundles } = await CapacitorUpdater.list();
console.log('Available bundles:', bundles);

Elimina un bundle

await CapacitorUpdater.delete({
  id: 'bundle-id'
});

Ottieni il bundle corrente

const { bundle } = await CapacitorUpdater.current();
console.log('Current bundle:', bundle.version);

Listener di eventi

Ascolta gli eventi di aggiornamento:

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

// Listen for download progress
CapacitorUpdater.addListener('download', (info) => {
  console.log('Download progress:', info.percent);
});

// Listen for download completion
CapacitorUpdater.addListener('downloadComplete', (bundle) => {
  console.log('Download complete:', bundle.version);
});

// Listen for update failures
CapacitorUpdater.addListener('updateFailed', (error) => {
  console.error('Update failed:', error);
});

// Listen for successful updates
CapacitorUpdater.addListener('updateAvailable', (info) => {
  console.log('Update available:', info.version);
});

Opzioni di configurazione

Configura il plugin nel tuo capacitor.config.ts:

{
  plugins: {
    CapacitorUpdater: {
      // Auto-update settings
      autoUpdate: 'atBackground',
      updateUrl: 'https://api.example.com/updates',

      // Update behavior
      resetWhenUpdate: true,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

      // Stats collection
      statsUrl: 'https://api.example.com/stats',

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

Pattern di integrazione

Con Capgo Cloud

Il modo più semplice per iniziare:

// Install the Capgo CLI
bun add -g @capgo/cli

// Login to Capgo
npx @capgo/cli login

// Upload your first bundle
npx @capgo/cli bundle upload

// The plugin auto-updates from Capgo cloud

Guarda il guida Quickstart principale per i dettagli.

Aggiornamenti self-hosted

Configura il tuo server di update:

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      updateUrl: 'https://your-server.com/api/check-update'
    }
  }
}

Il tuo server deve restituire:

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

Vedi Modalità Self-Hosted per tutti i dettagli.

Flusso di update manuale

Controllo totale sugli update:

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

async function checkAndUpdate() {
  // Check for updates from your server
  const response = await fetch('https://api.example.com/check-update');
  const { version, url } = await response.json();

  // Download the update
  const bundle = await CapacitorUpdater.download({
    url,
    version
  });

  // Notify bundle is ready
  await CapacitorUpdater.notifyAppReady();

  // Set as next version
  await CapacitorUpdater.set({ id: bundle.id });

  // Reload when ready
  await CapacitorUpdater.reload();
}

Best practice

• Chiamare sempre notifyAppReady() quando la tua app si carica correttamente
• Testa bene gli update prima del rilascio in produzione
• Implementa una gestione corretta degli errori per i problemi di rete
• Usa i numeri di versione in modo coerente
• Mantieni i bundle piccoli per download più veloci
• Monitora il tasso di successo degli update

Prossimi passi

• Riferimento plugin API - Documentazione API completa
• Impostazioni del plugin - Tutte le opzioni di configurazione
• Eventi - Eventi di aggiornamento disponibili
• Modalità Self-Hosted - Gestisci il tuo server di update
• Sviluppo locale - Testa gli update localmente
• Debug - Guida al troubleshooting

Supporto

• Problemi noti - Problemi comuni e soluzioni
• Discussioni GitHub - Supporto della community
• Discord - Chat in tempo reale

Continua da Getting Started

Se stai usando Per iniziare per pianificare il lavoro sui plugin nativi, collegalo a Usando @capgo/capacitor-updater per la funzionalità nativa in Usando @capgo/capacitor-updater, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.