Riferimento all'Aggiornamento di Electron API

Questa pagina documenta tutte le metodologie, gli eventi e le opzioni di configurazione disponibili per l'aggiornamento di Electron.

Metodi di base

notifyAppReady()

Deve essere chiamato ogni volta che si avvia l'applicazione. Conferma che il pacchetto è stato caricato con successo e prevenire il rollback automatico.

await updater.notifyAppReady();

Attenzione

Se non viene chiamato entro appReadyTimeout (di default 10 secondi), l'aggiornamento viene considerato fallito e l'app torna alla versione precedente.

download(options)

Scarica un bundle da una URL.

const bundle = await updater.download({
  url: 'https://example.com/bundle.zip',
  version: '1.0.1',
  checksum: 'sha256-hash', // Optional but recommended
  sessionKey: '...', // For encrypted bundles
});

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
url	string	Sì	URL per scaricare il bundle
version	string	Sì	Identificatore della versione per il bundle
checksum	string	No	Checksum SHA256 per la verifica
sessionKey	string	No	Chiave di sessione per i bundle crittografati

Restituisce: BundleInfo oggetto con id, version, status

next(options)

Inserisci nella coda un bundle da caricare alla prossima riavvio dell'applicazione.

await updater.next({ id: 'bundle-id' });

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
id	stringa	Sì	ID del bundle per la coda

set(options)

Passare immediatamente a un bundle e ricaricare l'app.

await updater.set({ id: 'bundle-id' });

Parametri:

Opzione	Tipo	Richiesto	Descrizione
id	string	Sì	ID del bundle per l'attivazione

reload()

Ricarica manualmente l'applicazione con il bundle corrente.

await updater.reload();

delete(options)

Elimina un bundle dallo storage.

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

Parametri:

Opzione	Tipo	Richiesto	Descrizione
id	stringa	Sì	ID del bundle da eliminare

reset(options)

Resetta alla versione predefinita o alla versione del bundle più recente.

// Reset to builtin
await updater.reset({ toLastSuccessful: false });

// Reset to last successful bundle
await updater.reset({ toLastSuccessful: true });

Parametri:

Opzione	Tipo	Richiesto	Descrizione
toLastSuccessful	booleano	No	Se vero, resettare a bundle di successo precedente al posto di quello predefinito

Informazioni sul bundle

current()

Ottieni informazioni sul bundle corrente e sulla versione nativa.

const info = await updater.current();
// { bundle: { id, version, status }, native: '1.0.0' }

list(options)

Elencare tutti i bundle scaricati.

const bundles = await updater.list();
// [{ id, version, status, downloaded, checksum }, ...]

getNextBundle()

Ottieni il bundle in attesa del prossimo riavvio.

const next = await updater.getNextBundle();
// { id, version, status } or null

getFailedUpdate()

Ottieni informazioni sull'ultima aggiornamento fallito (utili per la debuggazione dei rollback).

const failed = await updater.getFailedUpdate();
// { id, version, reason } or null

Esegui la versione integrata()

Esegui la versione integrata con il binario dell'applicazione.

const version = await updater.getBuiltinVersion();
// '1.0.0'

Controllo Aggiornamenti

Esegui l'ultima versione (options)

Controlla il server per la versione disponibile più recente.

const latest = await updater.getLatest();

if (latest.url && !latest.error) {
  // Update available
  console.log('New version:', latest.version);
  console.log('Download URL:', latest.url);
} else if (latest.error) {
  console.error('Error checking updates:', latest.error);
}

Ritorna:

Proprietà	Tipo	Descrizione
url	stringa	URL di download (vuoto se non ci sono aggiornamenti)
version	stringa	Versione disponibile
checksum	stringa	Checksum SHA256
sessionKey	stringa	Chiave di sessione di crittografia
error	stringa	Messaggio di errore se il controllo è fallito
message	string	Messaggio del server

Gestione dei canali

setChannel(options)

Assegna il dispositivo a un canale specifico.

await updater.setChannel({ channel: 'beta' });

unsetChannel(options)

Rimuovi l'assegnazione del canale e utilizza il valore predefinito.

await updater.unsetChannel();

ottieniCanale()

Ottieni l'assegnazione del canale corrente.

const channel = await updater.getChannel();
// { channel: 'production', status: 'set' }

elencaNazionali()

Elenca tutti i canali disponibili per questa app.

const channels = await updater.listChannels();
// ['production', 'beta', 'staging']

Condizioni di ritardo

Controlla quando vengono applicate le aggiornamenti scaricati.

setMultiDelay(options)

Imposta le condizioni che devono essere soddisfatte prima che un aggiornamento venga applicato.

// Wait for app to be backgrounded
await updater.setMultiDelay({
  delayConditions: [{ kind: 'background' }]
});

// Wait until specific date
await updater.setMultiDelay({
  delayConditions: [{ kind: 'date', value: '2024-12-25T00:00:00Z' }]
});

// Wait for app to be killed and restarted
await updater.setMultiDelay({
  delayConditions: [{ kind: 'kill' }]
});

// Multiple conditions (all must be met)
await updater.setMultiDelay({
  delayConditions: [
    { kind: 'background' },
    { kind: 'date', value: '2024-12-25T00:00:00Z' }
  ]
});

Tipi di condizione di ritardo:

Tipo	Valore	Descrizione
background	Durata facoltativa (ms)	Attendere che l'app venga messa in background
kill	-	Attendere che l'app venga uccisa e riavviata
date	Stringa di data ISO	Attendere una data/ora specifica
nativeVersion	Version string	Attendere l'aggiornamento dell'app nativa

cancelDelay()

Cancella tutte le condizioni di ritardo e applica l'aggiornamento immediatamente alla prossima verifica.

await updater.cancelDelay();

Identificazione del dispositivo

getDeviceId()

Ottieni l'identificatore univoco del dispositivo.

const deviceId = await updater.getDeviceId();
// 'uuid-xxxx-xxxx-xxxx'

impostaIdPersonalizzato(options)

Imposta un identificatore personalizzato per il dispositivo (utile per gli analytics).

await updater.setCustomId({ customId: 'user-123' });

Configurazione

impostaUrlAggiornamento(options)

Cambia l'URL del server di aggiornamento in esecuzione.

await updater.setUpdateUrl({ url: 'https://my-server.com/updates' });

Nota

Richiede allowModifyUrl: true nelle opzioni del costruttore.

impostaUrlStatistica(options)

Cambia l'URL di reporting delle statistiche.

await updater.setStatsUrl({ url: 'https://my-server.com/stats' });

impostaUrlCanale(options)

Cambia l'URL di gestione del canale.

await updater.setChannelUrl({ url: 'https://my-server.com/channel' });

impostaIdApp(options)

Cambia l'ID dell'applicazione in esecuzione.

await updater.setAppId({ appId: 'com.example.newapp' });

Nota

Richiede allowModifyAppId: true nel le opzioni del costruttore.

getAppId()

Ottieni l'ID dell'applicazione corrente.

const appId = await updater.getAppId();

Debug

impostaMenuDiDebug(options)

Abilita o disabilita il menu di debug.

await updater.setDebugMenu({ enabled: true });

isDebugMenuEnabled()

Controlla se il menu di debug è abilitato.

const enabled = await updater.isDebugMenuEnabled();

Eventi

Ascolta gli eventi di aggiornamento utilizzando addListener:

updater.addListener('eventName', (event) => {
  // Handle event
});

Eventi disponibili

Evento	Payload	Descrizione
download	{ percent, status }	Aggiornamenti sul progresso del download
updateAvailable	{ bundle }	Disponibile un nuovo aggiornamento
noNeedUpdate	{ message }	Già aggiornato
downloadComplete	{ bundle }	Download completato con successo
downloadFailed	{ bundle, error }	Download fallito
breakingAvailable	{ bundle }	Aggiornamento incompatibile (richiede aggiornamento nativo)
updateFailed	{ bundle, reason }	Fallito l'installazione dell'aggiornamento
appReloaded	{}	L'app è stata riavviata
appReady	{}	notifyAppReady() è stato chiamato

Esempio: Gestione completa degli eventi

// Progress tracking
updater.addListener('download', (event) => {
  updateProgressBar(event.percent);
});

// Update available notification
updater.addListener('updateAvailable', (event) => {
  showNotification(`Update ${event.bundle.version} available!`);
});

// Handle completion
updater.addListener('downloadComplete', async (event) => {
  // Queue for next restart
  await updater.next({ id: event.bundle.id });
  showNotification('Update will apply on next restart');
});

// Handle failures
updater.addListener('updateFailed', (event) => {
  console.error('Update failed:', event.reason);
  reportError(event);
});

Opzioni per il costruttore

Opzioni di configurazione complete per ElectronUpdater:

const updater = new ElectronUpdater({
  // Required
  appId: 'com.example.app',

  // Version override
  version: '1.0.0', // Override builtin version detection

  // Server URLs
  updateUrl: 'https://plugin.capgo.app/updates',
  channelUrl: 'https://plugin.capgo.app/channel_self',
  statsUrl: 'https://plugin.capgo.app/stats',

  // Behavior
  autoUpdate: true,           // Enable automatic update checks
  appReadyTimeout: 10000,     // Milliseconds before rollback (default: 10000)
  autoDeleteFailed: true,     // Auto-delete failed bundles
  autoDeletePrevious: true,   // Auto-delete old bundles
  resetWhenUpdate: true,      // Reset to builtin on native update

  // Channels
  defaultChannel: 'production',

  // Direct Update Mode
  directUpdate: false,        // 'atInstall' | 'onLaunch' | 'always' | false

  // Security
  publicKey: '...',           // RSA public key for E2E encryption

  // Dynamic Configuration
  allowModifyUrl: false,      // Allow runtime URL changes
  allowModifyAppId: false,    // Allow runtime App ID changes
  persistCustomId: false,     // Persist custom ID across updates
  persistModifyUrl: false,    // Persist URL changes

  // Debug
  debugMenu: false,           // Enable debug menu (Ctrl+Shift+D)
  disableJSLogging: false,    // Disable console logs

  // Periodic Updates
  periodCheckDelay: 0,        // Seconds between auto-checks (0 = disabled, min 600)
});

Continua da Electron Updater API Reference

Se stai utilizzando Aggiornatore di Electron API Riferimento per pianificare il dashboard e le API operazioni, connettilo con Utilizzando @capgo/electron-updater per la capacità nativa in Utilizzando @capgo/electron-updater, Panoramica di API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi di API per i dettagli di implementazione in Chiavi di API, e Dispositivi per i dettagli di implementazione in Dispositivi.