Référence Electron Updater API

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

Méthodes de base

notifyAppReady()

Doit être appelée à chaque lancement de l'application. Confirme que le bundle a été chargé avec succès et empêche le redémarrage automatique.

await updater.notifyAppReady();

Attention

Si elle n'est pas appelée dans les appReadyTimeout (10 secondes par défaut), l'update est considéré comme échoué et l'application revient à la version précédente.

download(options)

Télécharger un bundle à partir d'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	Obligatoire	Description
url	chaîne	Oui	URL à partir de laquelle télécharger le bundle
version	chaîne	Oui	Identifiant de version pour le bundle
checksum	chaîne	Non	Checksum SHA256 pour la vérification
sessionKey	chaîne	Non	Clé de session pour les bundles chiffrés

Renvoie : BundleInfo un objet avec id, version, status

next(options)

File d'attente un bundle pour le prochain redémarrage de l'application.

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

Paramètres :

Option	Type	Obligatoire	Description
id	chaîne	Oui	Identifiant de bundle à file d'attente

set(options)

Passer immédiatement à un bundle et recharger l'application.

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

Paramètres :

Option	Type	Obligatoire	Description
id	chaîne	Oui	Identifiant de bundle à activer

reload()

Récharger manuellement l'application avec le bundle actuel.

await updater.reload();

delete(options)

Supprimer un bundle du stockage.

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

Paramètres :

Option	Type	Obligatoire	Description
id	chaîne	Oui	ID de bundle à supprimer

reset(options)

Réinitialiser vers la version intégrée ou la dernière mise à jour réussie.

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

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

Paramètres :

Option	Type	Obligatoire	Description
toLastSuccessful	boolean	Non	Si vrai, réinitialisez à la dernière mise à jour réussie au lieu de la version intégrée

Informations sur le paquet

actuel()

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

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

list(options)

Affichez la liste de tous les paquets téléchargés.

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

getNextBundle()

Récupère le bundle programmé pour la prochaine redémarrage.

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 les débogages de retours en arrière).

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

getBuiltinVersion()

Récupère la version embarquée avec le fichier binaire de l'application.

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

Vérification des mises à jour

getLatest(options)

Vérifiez le serveur pour 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	chaîne	URL de téléchargement (vide si aucune mise à jour)
version	string	Version disponible
checksum	string	Vérification de checksum SHA256
sessionKey	string	Clé de session de cryptage
error	string	Message d'erreur si la vérification a échoué
message	string	Message du serveur

Gestion de la chaîne

setChannel(options)

Assigner le dispositif à un canal spécifique.

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

unsetChannel(options)

Supprimer l'assignation de canal et utiliser la valeur par défaut.

await updater.unsetChannel();

getChannel()

Obtenir la valeur d'assignation de canal actuelle.

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

listChannels()

Listez tous les canaux disponibles pour cette application.

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

Conditions de retard

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

setMultiDelay(options)

Définir les conditions qui doivent être remplies avant que l'update soit appliqué.

// 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 retard :

Type	Valeur	Description
background	Durée facultative (ms)	Attendre que l'application soit mis en arrière-plan
kill	-	Attendre que l'application soit tuée et redémarrée
date	Chaîne de date ISO	Attendre une date et heure spécifique
nativeVersion	Chaîne de version	Attendre une mise à jour de l'application native

annulerDelay()

Supprimer toutes les conditions de retard et appliquer la mise à jour immédiatement lors du prochain contrôle.

await updater.cancelDelay();

Identification de l'appareil

getDeviceId()

Obtenir l'identifiant unique de l'appareil.

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

setCustomId(options)

Définir un identifiant personnalisé pour l'appareil (utile pour les analyses).

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

Configuration

setUpdateUrl(options)

Changer l'URL du serveur de mise à jour en temps réel.

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

Note

Exige allowModifyUrl: true dans les options du constructeur.

setStatsUrl(options)

Modifier l'URL de rapport de statistiques.

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

setChannelUrl(options)

Modifier l'URL de gestion de canal.

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

setAppId(options)

Changer l'ID d'application en temps de cours.

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

Note

Exige allowModifyAppId: true dans les options du constructeur.

getAppId()

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

const appId = await updater.getAppId();

Débogage

setDebugMenu(options)

Activer ou désactiver le menu de débogage.

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

isDebugMenuEnabled()

Vérifiez si le menu de débogage est activé.

const enabled = await updater.isDebugMenuEnabled();

Événements

Écoutez les événements de mise à jour en utilisant addListener:

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

Événements disponibles

Événement	Contenu de l'événement	Description
download	{ percent, status }	Mise à jour de la progression de téléchargement
updateAvailable	{ bundle }	Une mise à jour nouvelle est disponible
noNeedUpdate	{ message }	Déjà à jour
downloadComplete	{ bundle }	Téléchargement terminé avec succès
downloadFailed	{ bundle, error }	Téléchargement échoué
breakingAvailable	{ bundle }	Une mise à jour incompatible est 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)
});

Continuez avec Electron Updater API Reference

Si vous utilisez Electron Updater API Reference pour planifier le tableau de bord et les opérations API, connectez-l’avec En utilisant @capgo/electron-updater pour la capacité native dans En utilisant @capgo/electron-updater, API Présentation pour les détails d'implémentation dans API Présentation Introduction pour les détails d'implémentation dans Introduction API Clés pour les détails d'implémentation dans API Clés, et Appareils pour les détails d'implémentation dans Appareils.