Electron Updater API Referenz

Diese Seite dokumentiert alle verfügbaren Methoden, Events und Konfigurationsoptionen für den Electron Updater.

Kernmethoden

notifyAppReady()

Muss bei jedem App-Start aufgerufen werden. Bestätigt, dass das Bundle erfolgreich geladen wurde, und verhindert einen automatischen Rollback.

await updater.notifyAppReady();

Achtung

Falls nicht innerhalb von appReadyTimeout (standardmäßig 10 Sekunden) aufgerufen wird, gilt das Update als fehlgeschlagen und die App rollt auf die vorherige Version zurück.

download(options)

Lädt ein Bundle von einer URL herunter.

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

Parameter:

Option	Typ	Erforderlich	Beschreibung
url	string	Ja	URL zum Download des Bundles
version	string	Ja	Versionsbezeichner für das Bundle
checksum	string	Nein	SHA256-Checksumme zur Verifizierung
sessionKey	string	Nein	Session-Schlüssel für verschlüsselte Bundles

Rückgabe: BundleInfo object mit id, version, status

next(options)

Queue a bundle to be loaded on next app restart.

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

Parameter:

Option	Typ	Erforderlich	Beschreibung
id	string	Ja	Bundle ID für die Warteschlange

set(options)

Sofort zu einem Bundle wechseln und die App neu laden.

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

Parameter:

Option	Typ	Erforderlich	Beschreibung
id	string	Ja	Bundle-ID zum Aktivieren

reload()

Lädt die App manuell mit dem aktuellen Bundle neu.

await updater.reload();

delete(options)

Löscht ein Bundle aus dem Speicher.

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

Parameter:

Option	Typ	Erforderlich	Beschreibung
id	string	Ja	Bundle ID zum Löschen

reset(options)

Zurücksetzen auf die eingebaute Version oder das letzte erfolgreiche Bundle.

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

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

Parameter:

Option	Typ	Erforderlich	Beschreibung
toLastSuccessful	boolean	Nein	If true, reset to last successful bundle instead of builtin

Bundle-Informationen

current()

Ruft Informationen zum aktuellen Bundle und der nativen Version ab.

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

list(options)

Listet alle heruntergeladenen Bundles auf.

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

getNextBundle()

Ruft das für den nächsten Neustart eingereihte Bundle ab.

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

getFailedUpdate()

Ruft Informationen zum letzten fehlgeschlagenen Update ab (nützlich zum Debuggen von Rollbacks).

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

getBuiltinVersion()

Ruft die Version ab, die mit der App-Binary ausgeliefert wurde.

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

Update-Prüfung

getLatest(options)

Fragt den Server nach der neuesten verfügbaren Version ab.

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

Rückgabe:

Eigenschaft	Typ	Beschreibung
url	string	Download-URL (leer, wenn kein Update)
version	string	Verfügbare Version
checksum	string	SHA256-Prüfsumme
sessionKey	string	Verschlüsselungssitzungsschlüssel
error	string	Fehlermeldung, wenn die Prüfung fehlgeschlagen ist
message	string	Servermeldung

Channel-Management

setChannel(options)

Weist das Gerät einem bestimmten Channel zu.

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

unsetChannel(options)

Kanalzuweisung entfernen und Standard verwenden.

await updater.unsetChannel();

getChannel()

Aktuelle Kanalzuweisung abrufen.

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

listChannels()

Alle verfügbaren Kanäle für diese App auflisten.

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

Delay-Bedingungen

Steuern Sie, wann heruntergeladene Updates angewendet werden.

setMultiDelay(options)

Legen Sie Bedingungen fest, die erfüllt sein müssen, bevor ein Update angewendet wird.

// 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' }
  ]
});

Typen von Delay Conditions:

Typ	Wert	Beschreibung
background	Optionale Dauer (ms)	Warten, bis die App im Hintergrund ist
kill	-	Warten, bis die App beendet und neu gestartet wird
date	ISO-Datumszeichenkette	Bis zu einem bestimmten Datum/Zeit warten
nativeVersion	Versionszeichenkette	Auf native App-Updates warten

cancelDelay()

Alle Verzögerungsbedingungen löschen und das Update beim nächsten Check sofort anwenden.

await updater.cancelDelay();

Geräteidentifikation

getDeviceId()

Ruft die eindeutige Geräte-ID ab.

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

setCustomId(options)

Legt eine benutzerdefinierte ID für das Gerät fest (nützlich für Analytics).

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

Konfiguration

setUpdateUrl(options)

Ändert die Update-Server-URL zur Laufzeit.

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

Hinweis

Erfordert allowModifyUrl: true in den Konstruktor-Optionen.

setStatsUrl(options)

Ändert die URL für die Statistik-Übermittlung.

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

setChannelUrl(options)

Ändert die URL für das Channel-Management.

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

setAppId(options)

Ändert die App-ID zur Laufzeit.

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

Hinweis

Erfordert allowModifyAppId: true in den Konstruktor-Optionen.

getAppId()

Ruft die aktuelle App-ID ab.

const appId = await updater.getAppId();

Debuggen

setDebugMenu(options)

Aktiviert oder deaktiviert das Debug-Menü.

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

isDebugMenuEnabled()

Prüft, ob das Debug-Menü aktiviert ist.

const enabled = await updater.isDebugMenuEnabled();

Events

Update-Events abhören mit addListener:

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

Verfügbare Events

Event	Payload	Beschreibung
download	{ percent, status }	Updates zum Download-Fortschritt
updateAvailable	{ bundle }	Neues Update verfügbar
noNeedUpdate	{ message }	Bereits auf dem neuesten Stand
downloadComplete	{ bundle }	Download erfolgreich abgeschlossen
downloadFailed	{ bundle, error }	Download fehlgeschlagen
breakingAvailable	{ bundle }	Inkompatibles Update verfügbar (erfordert natives Update)
updateFailed	{ bundle, reason }	Update-Installation fehlgeschlagen
appReloaded	{}	App wurde neu geladen
appReady	{}	notifyAppReady() wurde aufgerufen

Beispiel: Vollständiges Event-Handling

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

Constructor-Optionen

Alle Konfigurationsoptionen für 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)
});

Weiter geht's mit der Electron Updater API Referenz

Wenn du es nutzt Electron Updater API Referenz um Dashboard- und API-Operationen zu planen, verbinde es mit @capgo/electron-updater verwenden für die native Funktionalität bei „@capgo/electron-updater verwenden“, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.