Referencia del Actualizador de Electron API

Esta página documenta todos los métodos, eventos y opciones de configuración disponibles para el Actualizador de Electron.

Métodos de Núcleo

notificarAplicaciónListo()

Deberá llamarse en cada lanzamiento de la aplicación. Confirma que el paquete se ha cargado con éxito y evita el rollback automático.

await updater.notifyAppReady();

Advertencia

Si no se llama dentro de appReadyTimeout (10 segundos por defecto), la actualización se considera fallida y la aplicación regresa a la versión anterior.

descargar(options)

Descargar un paquete desde una 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
});

Parámetros:

Opción	Tipo	Requerido	Descripción
url	cadena	Sí	URL para descargar el paquete desde
version	cadena	Sí	Identificador de versión para el paquete
checksum	cadena	No	Checksum SHA256 para verificar
sessionKey	cadena	No	Clave de sesión para paquetes cifrados

Devuelve: BundleInfo objeto con id, version, status

next(options)

Coloque un paquete en cola para cargar en el próximo reinicio de la aplicación.

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

Parámetros:

Opción	Tipo	Requerido	Descripción
id	cadena	Sí	ID de paquete para la cola

set(options)

Cambiar inmediatamente a un paquete y recargar la aplicación.

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

Parámetros:

Opción	Tipo	Requerido	Descripción
id	cadena	Sí	ID de paquete para activar

reload()

Recargar manualmente la aplicación con el paquete actual.

await updater.reload();

delete(options)

Eliminar un paquete de almacenamiento.

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

Parámetros:

Opción	Tipo	Requerido	Descripción
id	cadena	Sí	ID de paquete a eliminar

reset(options)

Restablecer a la versión predeterminada o el último paquete exitoso.

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

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

Parámetros:

Opción	Tipo	Requerido	Descripción
toLastSuccessful	booleano	No	Si es verdadero, restablecer a la última paquete exitoso en lugar de la predeterminada

Información del paquete

__CAPGO_KEEP_0__

Obtenga información sobre el paquete actual y la versión nativa.

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

listar(opciones)

Listar todos los paquetes descargados.

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

getNextBundle()

Obtenga el paquete programado para la próxima reinicialización.

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

getFailedUpdate()

Obtenga información sobre la última actualización fallida (útil para depurar rollbacks).

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

getBuiltinVersion()

Obtenga la versión embarcada con el binario de la aplicación.

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

Verificación de actualizaciones

getLatest(options)

Verifique el servidor para la versión más reciente 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);
}

Devuelve:

Propiedad	Tipo	Descripción
url	cadena	URL de descarga (vacía si no hay actualización)
version	cadena	Versión disponible
checksum	cadena	Checksum SHA256
sessionKey	cadena	Clave de sesión de cifrado
error	cadena	Mensaje de error si la comprobación falló
message	cadena	Mensaje del servidor

Gestión de canales

asignarCanal(opciones)

Asignar el dispositivo a un canal específico.

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

unsetChannel(options)

Quitar asignación de canal y usar el valor por defecto.

await updater.unsetChannel();

getChannel()

Obtener la asignación de canal actual.

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

listChannels()

Mostrar todos los canales disponibles para esta aplicación.

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

Condiciones de retraso

Controla cuándo se aplican las actualizaciones descargadas.

__CAPGO_KEEP_0__

Establece las condiciones que deben cumplirse antes de aplicar una actualización.

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

Tipos de condiciones de retraso:

Tipo	Valor	Descripción
background	Duración opcional (ms)	Esperar a que la aplicación esté en segundo plano
kill	-	Esperar a que la aplicación sea eliminada y reiniciada
date	Cadena de fecha ISO	Esperar hasta una fecha/hora específica
nativeVersion	Cadena de versión	Esperar a que se actualice la aplicación nativa

cancelDelay()

Deshacer todas las condiciones de retraso y aplicar la actualización inmediatamente en la próxima comprobación.

await updater.cancelDelay();

Identificación del dispositivo

getDeviceId()

Obtenga el identificador único del dispositivo.

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

setCustomId(options)

Establezca un identificador personalizado para el dispositivo (útil para análisis).

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

Configuración

setUpdateUrl(options)

Cambie la URL del servidor de actualizaciones en tiempo de ejecución.

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

Nota

Requiere allowModifyUrl: true en las opciones del constructor.

Sección titulada “setStatsUrl(options)”

Copiar a portapapeles

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

setChannelUrl(options)

Cambie la URL de gestión de canales.

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

setAppId(options)

Cambie el ID de la aplicación en tiempo de ejecución.

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

Nota

Requiere allowModifyAppId: true en las opciones del constructor.

getAppId()

Obtenga el ID de la aplicación actual.

const appId = await updater.getAppId();

Depuración

setDebugMenu(options)

Habilitar o deshabilitar el menú de depuración.

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

isDebugMenuEnabled()

Verifique si el menú de depuración está habilitado.

const enabled = await updater.isDebugMenuEnabled();

Eventos

Escuchar eventos de actualización utilizando addListener:

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

Eventos Disponibles

Evento	Payload	Descripción
download	{ percent, status }	Actualizaciones de progreso de descarga
updateAvailable	{ bundle }	Nueva actualización disponible
noNeedUpdate	{ message }	Actualizado ya
downloadComplete	{ bundle }	Descarga finalizada con éxito
downloadFailed	{ bundle, error }	Descarga fallida
breakingAvailable	{ bundle }	Actualización incompatible disponible (requiere actualización nativa)
updateFailed	{ bundle, reason }	Falló la instalación de la actualización
appReloaded	{}	Se recargó la aplicación
appReady	{}	notifyAppReady() se llamó

Ejemplo: Manejo completo de eventos

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

Opciones del constructor

Opciones de configuración completas para 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)
});

Sigue adelante desde el actualizador de Electron API Referencia

Si estás utilizando Referencia del actualizador de Electron API para planificar la consola y las operaciones API, conecta con Usando @capgo/electron-updater para la capacidad nativa en Usando @capgo/electron-updater, API Resumen para el detalle de implementación en API Resumen, Introducción para el detalle de implementación en Introduction, API Claves para el detalle de implementación en API Claves, y Dispositivos para el detalle de implementación en Dispositivos.