Elektron-Updater API-Referenz

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

Kernmethoden

notifyAppReady()

Muss auf jedem Anwendungsstart aufgerufen werden. Bestätigt die erfolgreiche Laden des Bundles und verhindert automatische Rückschritte.

await updater.notifyAppReady();

Vorsicht

Wenn nicht innerhalb von appReadyTimeout (Standard 10 Sekunden), wird die Aktualisierung als fehlgeschlagen betrachtet und die App wird auf die vorherige Version zurückgesetzt.

download(options)

Ein Bundle von einer URL herunterladen.

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	Ziel-Sprache	Ja	URL zum Herunterladen der Bundle
version	Ja	Versionen-Bezeichner für das Bundle	Kein
checksum	SHA256-Prüfsumme zur Verifizierung	Kein	Sitzungs-Schlüssel für verschlüsselte Bundle
sessionKey	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__	__CAPGO_KEEP_0__

Rückgabewert: BundleInfo Objekt mit id, version, status

next(options)

Ein Bundle in der Warteschlange für das Laden bei der nächsten Anwendungsneustart anlegen.

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

Parameter:

Option	Typ	Erforderlich	Beschreibung
id	Zeichenfolge	Ja	Bundle-ID, um die Warteschlange zu befüllen

set(options)

Sofort zu einem Bundle wechseln und die App neu laden.

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

Parameter:

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

reload()

Mit der aktuellen Bundle manuell die App neu laden.

await updater.reload();

delete(options)

Ein Bundle aus dem Speicher löschen.

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 Standardversion oder die 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	Wenn wahr, zurücksetzen auf letzte erfolgreiche Bundle anstatt auf Builtin

Bundle Informationen

aktuell()

Ermitteln Sie Informationen über das aktuelle Bundle und die native Version.

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

list(options)

Alle heruntergeladenen Pakete auflisten.

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

getNextBundle()

Das für das nächste Neustarten anstehende Paket abrufen.

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

getFailedUpdate()

Informationen über die letzte fehlgeschlagene Aktualisierung abrufen (wirksam für Debugging von Rollbacks).

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

getBuiltinVersion()

Ermitteln Sie die mit der App-Binary gelieferte Version.

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

Aktualisierungsprüfung

getLatest(options)

Überprüfen Sie den Server auf die neueste verfügbare Version.

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ückgabewert:

Eigenschaft	Typ	Beschreibung
url	__CAPGO_KEEP_0__	Herunterladungs-URL (leer, wenn keine Aktualisierung vorhanden)
version	__CAPGO_KEEP_0__	Verfügbare Version
checksum	__CAPGO_KEEP_0__	SHA256-Prüfsumme
sessionKey	__CAPGO_KEEP_0__	Verschlüsselungssitzungsschlüssel
error	__CAPGO_KEEP_0__	Fehlermeldung bei fehlgeschlagener Überprüfung
message	string	Server-Nachricht

Kanalverwaltung

setChannel(options)

Zuweisen Sie das Gerät einer bestimmten Kanal zuzuweisen.

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

unsetChannel(options)

Entfernen Sie die Kanalzuweisung und verwenden Sie die Standard-Einstellung.

await updater.unsetChannel();

getChannel()

Ermitteln Sie die aktuelle Kanalzuweisung.

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

listChannels()

Liste aller verfügbaren Kanäle für diese App.

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

Verzögerungsbedingungen

Bestimmen Sie, wann heruntergeladene Updates angewendet werden.

setMultiDelay(options)

Legen Sie Bedingungen fest, die erfüllt sein müssen, bevor eine Aktualisierung 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' }
  ]
});

Verzögerungsbedingungstypen:

Art	Wert	Beschreibung
background	Optionale Dauer (ms)	Warten, bis die App in den Hintergrund geschoben wird
kill	-	Warten, bis die App beendet und neu gestartet wird
date	ISO-Datumszeichenfolge	Warten, bis eine bestimmte Uhrzeit
nativeVersion	Versionsnummer	Warten auf native App-Update

__CAPGO_KEEP_0__

Alle Verzögerungsbedingungen löschen und Update sofort bei der nächsten Überprüfung anwenden.

await updater.cancelDelay();

Geräteidentifikation

getDeviceId()

Geräte-Unique-Identifier abrufen.

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

setCustomId(options)

Setzen Sie einen benutzerdefinierten Geräteidentifier (nützlich für Analysen).

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

Konfiguration

setUpdateUrl(options)

Ändern Sie die Update-Server-URL während der Laufzeit.

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

Hinweis

Benötigt allowModifyUrl: true im Konstruktor-Optionen.

setStatsUrl(options)

Ändern Sie die URL für die Statistikberichterstattung.

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

setChannelUrl(options)

Ändern Sie die URL für die Kanalverwaltung.

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

setAppId(options)

Ändern Sie die App-ID während der Ausführung.

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

Hinweis

Erforderlich allowModifyAppId: true in den Konstruktoroptionen.

getAppId()

Ermitteln Sie die aktuelle App-ID.

const appId = await updater.getAppId();

Debug

Debug-Menü einrichten (options)

Das Debug-Menü aktivieren oder deaktivieren.

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

istDebugMenuAktiviert()

Überprüfen, ob das Debug-Menü aktiviert ist.

const enabled = await updater.isDebugMenuEnabled();

Ereignisse

Hören Sie auf Update-Ereignisse mit addListener:

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

Verfügbare Ereignisse

Ereignis	Payload	Beschreibung
download	{ percent, status }	Download-Progress-Updates
updateAvailable	{ bundle }	Neue Aktualisierung verfügbar
noNeedUpdate	{ message }	Aktuell auf dem neuesten Stand
downloadComplete	{ bundle }	Download erfolgreich abgeschlossen
downloadFailed	{ bundle, error }	Download fehlgeschlagen
breakingAvailable	{ bundle }	Inkompatible Aktualisierung verfügbar (erfordert native Aktualisierung)
updateFailed	{ bundle, reason }	Fehler beim Installieren der Aktualisierung
appReloaded	{}	Die App wurde neu geladen
appReady	{}	notifyAppReady() wurde aufgerufen

Beispiel: Vollständige Ereignisbearbeitung

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

Konstruktor-Optionen

Vollständige 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)
});