Aggiornamento di Electron API Reference

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 chiamata ogni volta che si avvia l'applicazione. Conferma che il pacchetto è stato caricato con successo e impedisce il rollback automatico.

await updater.notifyAppReady();

Attenzione

Se non viene chiamata entro appReadyTimeout (10 secondi di default), l'aggiornamento viene considerato fallito e l'applicazione 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	Richiesto	Descrizione
url	stringa	Sì	URL da cui scaricare il bundle
version	Lingua obiettivo: Italiano	Sì	Identificatore della versione per il bundle
checksum	stringa	No	Checksum SHA256 per la verifica
sessionKey	stringa	No	Chiave di sessione per i bundle crittografati

Ritorna: BundleInfo oggetto con id, version, status

next(options)

Incolli una raccolta per essere caricata alla prossima riavvio dell'applicazione.

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

Parametri:

Opzione	Tipo	Richiesto	Descrizione
id	stringa	Sì	ID della raccolta da incolliare

set(options)

Passa immediatamente a un bundle e ricarica l'applicazione.

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

Parametri:

Opzione	Tipo	Obbligatorio	Descrizione
id	stringa	Sì	ID del bundle da attivare

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	Obbligatorio	Descrizione
id	string	Sì	ID del bundle da eliminare

reset(options)

Resetta alla versione predefinita 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	Richiesto	Descrizione
toLastSuccessful	boolean	No	Se vero, resettare a bundle di successo precedente al posto di quello predefinito

Informazioni sul bundle

current()

Ottenere 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 pacchetto in coda per il prossimo riavvio.

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

getFailedUpdate()

Ottieni informazioni sull'ultima aggiornamento fallito (utile per i rollback di debug).

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

getBuiltinVersion()

Ottieni la versione consegnata con il binario dell'app.

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

Verifica dell'aggiornamento

getLatest(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	__CAPGO_KEEP_0__	Versione disponibile
checksum	__CAPGO_KEEP_0__	Checksum SHA256
sessionKey	__CAPGO_KEEP_0__	Chiave di sessione di crittografia
error	__CAPGO_KEEP_0__	Messaggio di errore se il controllo fallisce
message	__CAPGO_KEEP_0__	Messaggio del server

Gestione dei canali

impostaCanale(options)

Assegna il dispositivo a un canale specifico.

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

rimuoviCanale(options)

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

await updater.unsetChannel();

ottieniCanale()

Ottenere l'assegnazione del canale corrente.

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

listChannels()

Elencare tutti i canali disponibili per questa app.

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

Condizioni di ritardo

Controllare quando vengono applicate le aggiornamenti scaricati.

setMultiDelay(options)

Impostare 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)	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	Stringa di versione	Attendere l'aggiornamento nativo dell'app

cancelDelay()

Elimina 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'

setCustomId(options)

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

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

Configurazione

setUpdateUrl(options)

Cambia l'URL del server di aggiornamento in esecuzione.

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

Nota

Richiesto allowModifyUrl: true nei parametri di costruzione.

setStatsUrl(options)

Cambia l'URL di reporting delle statistiche.

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

setChannelUrl(options)

Cambia l'URL di gestione del canale.

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

setAppId(options)

Cambia l'ID dell'applicazione in esecuzione.

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

Nota

Richiede allowModifyAppId: true nelle opzioni del costruttore.

getAppId()

Ottieni l'ID App corrente.

const appId = await updater.getAppId();

Debug

setDebugMenu(options)

Abilita o disabilita il menu di debug.

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

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

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 }	Aggiornamento nuovo disponibile
noNeedUpdate	{ message }	Già aggiornato
downloadComplete	{ bundle }	Download completato con successo
downloadFailed	{ bundle, error }	Download fallito
breakingAvailable	{ bundle }	Aggiornamento incompatibile disponibile (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 del costruttore

Opzioni di configurazione completa 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)
});