Inizio

Installazione

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

Avvio rapido

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

Questa guida di avvio copre i dettagli tecnici del plugin per gli utenti avanzati che desiderano comprendere i meccanismi sottostanti o implementare aggiornamenti self-hosted.

Panoramica

Il plugin Capacitor Updater consente l'aggiornamento over-the-air (OTA) per le tue Capacitor applicazioni. Ciò ti consente di inviare aggiornamenti all'app senza dover passare dalle revisioni delle app store.

Come Funziona

1. Download del Pacchetto: Il plugin scarica i pacchetti di aggiornamento (file ZIP contenenti i tuoi asset web)
2. Estrazione: I pacchetti vengono estratti nel storage del dispositivo
3. Hot Reload: L'app si sposta sul nuovo pacchetto senza richiedere un riavvio
4. Fallback: Se un aggiornamento fallisce, l'app si ripristina alla versione precedente funzionante

Modalità di utilizzo

1. Modalità di aggiornamento automatico (Consigliata)

La modalità più semplice per utilizzare il plugin con la 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: true,
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. Modalità manuale

Per un controllo avanzato sul processo di aggiornamento:

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

Non è richiesta alcuna configurazione aggiuntiva. Il plugin funziona direttamente dal box.

Android

Non è richiesta alcuna configurazione aggiuntiva. Il plugin funziona direttamente dal box.

Utilizzo base 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 Bundle Attivo

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

Carica con 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 nei tuoi capacitor.config.ts:

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

      // Update behavior
      resetWhenUpdate: true,
      directUpdate: false,

      // Version settings
      version: '1.0.0',

      // Security
      allowModifyUrl: false,

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

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

Modelli di integrazione

Con Capgo Cloud

La migliore via 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

Vedi il guida di avvio rapido principale per i dettagli.

Aggiornamenti Auto-Hosted

Hosta il tuo server di aggiornamento:

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

Il tuo server dovrebbe restituire:

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

Vedi Modalità Auto-Hosted per ulteriori dettagli.

Flusso di Aggiornamento Manuale

Controllo completo sugli aggiornamenti:

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();
}

Pratiche Raccomandate

• Chiamare sempre notifyAppReady() quando il tuo app carica con successo
• Testare le aggiornamenti attentamente prima di pubblicarli in produzione
• Implementare un gestione degli errori appropriata per le fallite di rete
• Utilizzare i numeri di versione in modo coerente
• Tenere le dimensioni dei pacchetti piccole per scaricamenti più veloci
• Monitorare le tassi di successo degli aggiornamenti

Passaggi successivi

• Riferimento al plugin API - Documentazione completa di API
• Impostazioni Plugin - Tutte le opzioni di configurazione
• Eventi - Eventi di aggiornamento disponibili
• Modalità Auto-Hosted - Esegui il tuo proprio server di aggiornamento
• Sviluppo Locale - Testa gli aggiornamenti localmente
• Debugging - Guida di troubleshooting

Supporto

• Problemi Noti - Problemi comuni e soluzioni
• GitHub Discussioni - Supporto della comunità
• Discord - Chat in tempo reale