Référence Electron Updater API

Cette page documente toutes les méthodes, événements et options de configuration disponibles pour Electron Updater.

Méthodes principales

notifyAppReady()

À appeler à chaque lancement de l’application. Confirme que le bundle a été chargé avec succès et empêche le rollback automatique.

await updater.notifyAppReady();

Attention

S’il n’est pas appelé dans les appReadyTimeout (10 secondes par défaut), la mise à jour est considérée comme échouée et l’application revient à la version précédente.

download(options)

Télécharger un bundle depuis une 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
});

Paramètres :

Option	Type	Requis	Description
url	string	Oui	URL de téléchargement du bundle
version	string	Oui	Identifiant de version du bundle
checksum	string	Non	Checksum SHA256 pour vérification
sessionKey	string	Non	Clé de session pour les bundles chiffrés

Retourne : BundleInfo objet avec id, version, status

next(options)

Queue a bundle to be loaded on next app restart.

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

Paramètres :

Option	Type	Requis	Description
id	string	Oui	Bundle ID à mettre en file d'attente

set(options)

Bascule immédiatement vers un bundle et recharge l'app.

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

Paramètres :

Option	Type	Requis	Description
id	string	Oui	Bundle ID à activer

reload()

Recharge manuellement l'app avec le bundle actuel.

await updater.reload();

delete(options)

Supprime un bundle du stockage.

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

Paramètres :

Option	Type	Requis	Description
id	string	Oui	ID du bundle à supprimer

reset(options)

Réinitialiser vers la version intégrée ou le dernier bundle réussi.

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

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

Paramètres :

Option	Type	Requis	Description
toLastSuccessful	booléen	Non	Si true, réinitialise vers le dernier bundle réussi au lieu du bundle intégré

Informations sur le bundle

current()

Obtenez des informations sur le bundle actuel et la version native.

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

list(options)

Listez tous les bundles téléchargés.

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

getNextBundle()

Get the bundle queued for next restart.

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

getFailedUpdate()

Récupère des informations sur la dernière mise à jour échouée (utile pour déboguer les rollbacks).

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

getBuiltinVersion()

Récupère la version livrée avec le binaire de l’application.

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

Vérification des mises à jour

getLatest(options)

Vérifiez sur le serveur la dernière version disponible.

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

Retourne :

Propriété	Type	Description
url	string	Download URL (empty if no update)
version	string	Version disponible
checksum	string	Checksum SHA256
sessionKey	string	Clé de session de chiffrement
error	string	Message d’erreur si la vérification a échoué
message	string	Message du serveur

Gestion des canaux

setChannel(options)

Affecter l’appareil à un canal spécifique.

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

unsetChannel(options)

Supprime l’attribution de canal et utilise le canal par défaut.

await updater.unsetChannel();

getChannel()

Récupère l’attribution de canal actuelle.

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

listChannels()

Liste tous les canaux disponibles pour cette application.

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

Conditions de délai

Contrôlez quand les mises à jour téléchargées sont appliquées.

setMultiDelay(options)

Définissez les conditions qui doivent être remplies avant l’application d’une mise à jour.

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

Types de conditions de délai :

Type	Valeur	Description
background	Durée facultative (ms)	Attendre que l’application passe en arrière-plan
kill	-	Attendre que l’application soit tuée puis relancée
date	Chaîne de caractères ISO date	Attendre une date/heure spécifique
nativeVersion	Chaîne de caractères de version	Attendre une mise à jour native de l’application

cancelDelay()

Clear all delay conditions and apply update immediately on next check.

await updater.cancelDelay();

Identification de l'appareil

getDeviceId()

Récupère l’identifiant unique de l’appareil.

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

setCustomId(options)

Définit un identifiant personnalisé pour l’appareil (utile pour l’analyse).

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

Configuration

setUpdateUrl(options)

Modifier l’URL du serveur de mise à jour à l’exécution.

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

Remarque

Nécessite une allowModifyUrl: true dans les options du constructeur.

setStatsUrl(options)

Modifier l’URL de reporting des statistiques.

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

setChannelUrl(options)

Modifier l’URL de gestion des canaux.

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

setAppId(options)

Modifier l’App ID à l’exécution.

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

Remarque

Nécessite une allowModifyAppId: true dans les options du constructeur.

getAppId()

Récupérer l'ID de l'application actuel.

const appId = await updater.getAppId();

Débogage

setDebugMenu(options)

Activer ou désactiver le menu de debug.

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

isDebugMenuEnabled()

Vérifier si le menu de debug est activé.

const enabled = await updater.isDebugMenuEnabled();

Événements

Écouter les événements de mise à jour à l'aide de addListener:

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

Événements disponibles

Événement	Charge utile	Description
download	{ percent, status }	Mises à jour de la progression du téléchargement
updateAvailable	{ bundle }	Nouvelle mise à jour disponible
noNeedUpdate	{ message }	Already up-to-date
downloadComplete	{ bundle }	Téléchargement terminé avec succès
downloadFailed	{ bundle, error }	Échec du téléchargement
breakingAvailable	{ bundle }	Mise à jour incompatible disponible (mise à jour native requise)
updateFailed	{ bundle, reason }	Échec de l’installation de la mise à jour
appReloaded	{}	L’application a été rechargée
appReady	{}	notifyAppReady() a été appelé

Exemple : gestion complète des événements

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

Options du constructeur

Options de configuration complètes pour 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)
});

Poursuivez avec la référence Electron Updater API

Si vous utilisez Référence Electron Updater API pour planifier les opérations du dashboard et de API, connectez-l’avec Utiliser @capgo/electron-updater pour la fonctionnalité native dans « Utiliser @capgo/electron-updater », Aperçu de API pour les détails d'implémentation dans « Vue d'ensemble de API », Introduction pour les détails d'implémentation dans l'introduction, Clés API pour les détails d'implémentation dans « Clés API », et Appareils pour les détails d'implémentation dans Devices.