Référence de l'actualisation d'Electron API

Cette page documente toutes les méthodes, événements et options de configuration disponibles pour le Mise à jour 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 rollback automatique.

await updater.notifyAppReady();

Attention

Si elle n'est pas appelée dans 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	Yes	Identifiant de version pour le bundle
checksum	chaîne	No	Checksum SHA256 pour la vérification
sessionKey	chaîne	No	Clé de session pour les bundles chiffrés

Retourne : BundleInfo objet avec id, version, status

next(options)

File à charger lors du 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 à charger

set(options)

Immédiatement basculer vers 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()

Recharger manuellement l'application avec le bundle actuel.

await updater.reload();

delete(options)

Supprimer un bundle de 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 par défaut ou la dernière bundle 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 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()

Obtenez le bundle en attente pour le prochain redémarrage.

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

getFailedUpdate()

Obtenez 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()

Obtenez 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	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 canal

setChannel(options)

Attribuer le dispositif à un canal spécifique.

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

unsetChannel(options)

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

await updater.unsetChannel();

getChannel()

Obtenir la valeur actuelle de l'attribution de canal.

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

listCanaux()

Lister tous les canaux disponibles pour cette application.

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

Conditions de retard

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

setMultiDelay(options)

Définir les conditions qui doivent être remplies avant qu'une mise à jour soit appliquée.

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

cancelDelay()

Supprimer toutes les conditions de retard et appliquer la mise à jour immédiatement à la prochaine vérification.

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 d'actualisation en temps de cours.

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

Remarque

Exigences allowModifyUrl: true dans les options du constructeur.

setStatsUrl(options)

Changer l'URL de rapport de statistiques.

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

setChannelUrl(options)

Changer 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 exécution.

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

Note

Exige allowModifyAppId: true dans les options du constructeur.

getAppId()

Obtenez 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	Payload	Description
download	{ percent, status }	Mise à jour du progrès de téléchargement
updateAvailable	{ bundle }	Une nouvelle mise à jour est disponible
noNeedUpdate	{ message }	Vous êtes 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 }	L'installation de la mise à jour a échoué
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 à partir de la mise à jour d'Electron API Référence

Si vous utilisez Référence de la mise à jour d'Electron API pour planifier le tableau de bord et les opérations API, connectez-le à 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.