Getting Started

Installazione

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo competenze al tuo strumento AI utilizzando il seguente comando:

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

Poi utilizza 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 l'installazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito.

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 la guida di avvio rapido principale che copre sia l'installazione del plugin che l'integrazione cloud Capgo.

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

Panoramica

Il plugin di aggiornamento Capacitor consente gli aggiornamenti in tempo reale (OTA) per le tue applicazioni Capacitor. Ciò ti consente di inviare aggiornamenti al tuo app senza dover passare attraverso le recensioni delle app store.

Come Funziona

1. Scarica Bundle: Il plugin scarica i pacchetti di aggiornamento (file ZIP contenenti i tuoi asset web)
2. Estrazione: I bundle sono estratti sullo storage del dispositivo
3. Hot Reload: L'applicazione si passa al nuovo bundle senza richiedere un riavvio
4. Fallback: Se l'aggiornamento fallisce, l'applicazione si ripassa alla versione precedente funzionante

Usage Modes

1. Auto-Update Mode (Recommended)

Il modo 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: 'atBackground',
      updateUrl: 'https://your-update-server.com/api/updates'
    }
  }
}

2. Modalità manuale

Per un controllo avanzato del 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 subito dopo l'installazione.

Android

No configurazione aggiuntiva richiesta. Il plugin funziona subito.

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 nuovamente con bundle nuovo

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

Elenco Pacchetti

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

Elimina un Pacchetto

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

Ottieni il Pacchetto Corrente

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

Elenco 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'
    }
  }
}

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 rapida principale per ulteriori dettagli.

Aggiornamenti Auto-Hosted

Hosta il tuo proprio server di aggiornamento:

// Configure your update endpoint
{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: 'atBackground',
      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 completi.

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 si carica con successo
• Testare gli aggiornamenti attentamente prima di pubblicarli in produzione
• Gestisci correttamente gli errori di rete
• Usa numeri di versione coerenti
• Keep bundle sizes small for faster downloads
• Monitorare le percentuali di successo degli aggiornamenti

Next Steps

• Riferimento al plugin API Completa la documentazione del plugin API
• Impostazioni del plugin Tutte le opzioni di configurazione
• Eventi Aggiornamenti disponibili
• Modalità Auto-Hosted Esegui il tuo server di aggiornamento
• Sviluppo locale Testa gli aggiornamenti localmente
• Debugging - Guida di risoluzione dei problemi

Supporto

• Sottosezione intitolata “Supporto” Sottosezione intitolata “Supporto”
• GitHub Discussions Sottosezione intitolata “Continua da qui”
• Discord - Problemi comuni e soluzioni

__CAPGO_KEEP_0__ Discussioni

Se stai utilizzando Getting Started per pianificare il lavoro di plugin nativo, connettilo con Utilizzare @capgo/capacitor-aggiornatore per la capacità nativa in Utilizzare @capgo/capacitor-aggiornatore, Capgo Directory dei Plugin per il workflow del prodotto nella directory del plugin Capgo Capacitor Plugin da Capgo per la dettaglio di implementazione in Capacitor Plugin da Capgo, Aggiungere o Aggiornare i Plugin per il dettaglio di implementazione in Aggiungere o Aggiornare i Plugin, e Alternative Plugin Enterprise Ionic per il workflow del prodotto in Ionic Enterprise Plugin Alternatives.