Mise à jour Electron API Référence

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

Méthodes de base

notifyAppReady()

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

await updater.notifyAppReady();

Attention

Si ce n'est pas appelé dans appReadyTimeout le temps par défaut de 10 secondes), 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 de caractères	Oui	URL pour 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

Retour: BundleInfo objet avec id, version, status

next(options)

File d'attente un bundle pour qu'il soit chargé à la prochaine redémarrage de l'application.

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

Paramètres :

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

__CAPGO_KEEP_0__

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	ID de l'application pour l'activation

reload()

Recharger 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	Requis	Description
id	chaîne de caractères	Oui	ID de l'application à supprimer

reset(options)

Réinitialiser vers la version par défaut ou la dernière version de l'application.

// 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	boolean	Non	Si vrai, réinitialisez à la dernière bundle 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)

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

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

getNextBundle()

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

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

getFailedUpdate()

Récupérer des informations sur la dernière mise à jour échouée (utile pour le débogage des 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 de mise à 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	chaîne	Version disponible
checksum	chaîne	Checksum SHA256
sessionKey	Clé de session de chiffrement	Message d'erreur si la vérification a échoué
error	chaîne	__CAPGO_KEEP_0__
message	__CAPGO_KEEP_0__	Message du serveur

Gestion de canal

setChannel(options)

Attribuez le dispositif à un canal spécifique.

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

unsetChannel(options)

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

await updater.unsetChannel();

getChannel()

Récupérer la mise en relation actuelle du canal.

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

listChannels()

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 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 optionnelle (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	Attendez l'actualisation de l'application native

__CAPGO_KEEP_0__

Supprimer toutes les conditions de mise en attente et appliquer l'actualisation immédiatement lors du prochain contrôle.

await updater.cancelDelay();

Identification du dispositif

getDeviceId()

Obtenir l'identifiant unique du dispositif.

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

setCustomId(options)

Définir un identifiant personnalisé pour le dispositif (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' });

Remarque

Exige 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 de l'application en temps de cours.

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

Remarque

Requis allowModifyAppId: true __CAPGO_KEEP_0__ dans les options du constructeur.

getAppId()

Obtenir 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érifier si le menu de débogage est activé.

const enabled = await updater.isDebugMenuEnabled();

Événements

Écouter aux événements de mise à jour en utilisant addListener:

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

Événements disponibles

Événement	Payload	Description
download	{ percent, status }	Mises à jour de progression de téléchargement
updateAvailable	{ bundle }	Nouvelle mise à jour disponible
noNeedUpdate	{ message }	Déjà à jour
downloadComplete	{ bundle }	Téléchargement terminé avec succès
downloadFailed	{ bundle, error }	Téléchargement échoué
breakingAvailable	{ bundle }	Mise à jour incompatible (mise à jour native requise)
updateFailed	{ bundle, reason }	Échec de l'installation de la mise à jour
appReloaded	{}	L'application a été rechargée
appReady	{}	notifyAppReady() était 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 de 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)
});