Riferimento Electron Updater API

Questa pagina documenta tutti i metodi, gli eventi e le opzioni di configurazione disponibili per Electron Updater.

Metodi core

notifyAppReady()

Deve essere chiamato a ogni avvio dell'app. Conferma che il bundle è stato caricato correttamente e impedisce il rollback automatico.

await updater.notifyAppReady();

Attenzione

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

download(options)

Scarica un bundle da un 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 da cui scaricare il bundle
version	string	Sì	Identificatore di versione per il bundle
checksum	string	No	Checksum SHA256 per la verifica
sessionKey	string	No	Chiave di sessione per i bundle criptati

Restituisce: BundleInfo oggetto con id, version, status

next(options)

Mette in coda un bundle da caricare al prossimo riavvio dell'app.

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

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
id	string	Sì	Bundle ID da mettere in coda

set(options)

Passa immediatamente a un bundle e ricarica l'app.

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

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
id	string	Sì	Bundle ID da attivare

reload()

Ricarica manualmente l'app con il bundle corrente.

await updater.reload();

delete(options)

Elimina un bundle dallo storage.

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

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
id	string	Sì	Bundle ID da eliminare

reset(options)

Ripristina alla versione integrata o all'ultimo bundle riuscito.

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

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

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
toLastSuccessful	boolean	No	Se true, ripristina all'ultimo bundle riuscito invece che alla versione integrata

Informazioni sul bundle

current()

Ottieni informazioni sul bundle e sulla versione nativa correnti.

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

list(options)

Elenca tutti i bundle scaricati.

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

getNextBundle()

Ottieni il bundle in coda per il prossimo riavvio.

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

getFailedUpdate()

Ottieni informazioni sull'ultimo aggiornamento non riuscito (utile per il debug dei rollback).

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

getBuiltinVersion()

Ottieni la versione inclusa nel binario dell'app.

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

Verifica aggiornamenti

getLatest(options)

Verifica sul server la versione più recente disponibile.

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

Restituisce:

Proprietà	Tipo	Descrizione
url	string	URL di download (vuoto se nessun update)
version	string	Versione disponibile
checksum	string	Checksum SHA256
sessionKey	string	Chiave di sessione di crittografia
error	string	Messaggio di errore se il controllo fallisce
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 usa quello predefinito.

await updater.unsetChannel();

getChannel()

Ottieni l'assegnazione del canale corrente.

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

listChannels()

Elenca tutti i canali disponibili per questa app.

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

Condizioni di ritardo

Controlla quando vengono applicati gli aggiornamenti scaricati.

setMultiDelay(options)

Imposta le condizioni che devono essere soddisfatte prima di applicare un aggiornamento.

// 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)	Attendi che l'app passi in background
kill	-	Attendi che l'app venga terminata e riavviata
date	Stringa data ISO	Attendi fino a una data/ora specifica
nativeVersion	Stringa di versione	Attendi l'aggiornamento dell'app nativa

cancelDelay()

Rimuove tutte le condizioni di ritardo e applica l'aggiornamento immediatamente al prossimo controllo.

await updater.cancelDelay();

Identificazione del dispositivo

getDeviceId()

Ottieni l'identificativo univoco del dispositivo.

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

setCustomId(options)

Imposta un identificativo personalizzato per il dispositivo (utile per l'analytics).

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

Configurazione

setUpdateUrl(options)

Cambia l'URL del server di aggiornamento a runtime.

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

Nota

Richiede allowModifyUrl: true nelle opzioni del costruttore.

setStatsUrl(options)

Modifica l'URL di invio delle statistiche.

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

setChannelUrl(options)

Modifica l'URL di gestione del canale.

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

setAppId(options)

Cambia l'App ID a runtime.

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

Nota

Richiede allowModifyAppId: true nelle opzioni del costruttore.

getAppId()

Ottieni l'App ID corrente.

const appId = await updater.getAppId();

Debug

setDebugMenu(options)

Abilita o disabilita il menu di debug.

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

isDebugMenuEnabled()

Verifica se il menu di debug è abilitato.

const enabled = await updater.isDebugMenuEnabled();

Eventi

Ascolta gli eventi di aggiornamento usando addListener:

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

Eventi disponibili

Evento	Payload	Descrizione
download	{ percent, status }	Aggiornamenti di avanzamento del download
updateAvailable	{ bundle }	Nuovo aggiornamento disponibile
noNeedUpdate	{ message }	Già aggiornato
downloadComplete	{ bundle }	Download completato con successo
downloadFailed	{ bundle, error }	Download non riuscito
breakingAvailable	{ bundle }	Aggiornamento incompatibile disponibile (richiede un aggiornamento nativo)
updateFailed	{ bundle, reason }	Installazione dell'aggiornamento non riuscita
appReloaded	{}	L'app è stata ricaricata
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 del 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)
});

Passare da Electron Updater a API Reference

Se stai usando Riferimento Electron Updater API per pianificare le operazioni della dashboard e di API, collegalo a Utilizzo di @capgo/electron-updater per la funzionalità nativa in Utilizzo di @capgo/electron-updater, Panoramica API per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli di implementazione in Introduzione, Chiavi API per i dettagli di implementazione in Chiavi API, e Dispositivi per i dettagli di implementazione in Dispositivi.