API v1.0

Integration Guide for Electron Auto-Update

Learn how to integrate automatic updates into your Electron application using our release management platform. This guide covers manual downloads, API endpoints, and complete auto-update configuration.

Manual Download
Download binaries directly from the releases page
Auto-Update
Configure automatic updates in your Electron app
API Reference
Complete REST API documentation

Getting Started

Our platform provides a simple and secure way to distribute updates for your Electron application. You can either download releases manually or configure automatic updates using our API.

Base URL: All API endpoints are available at your deployed instance URL. Replace YOUR_DOMAIN with your actual domain.

Supported Platforms

🪟

Windows

.exe

win32
🍎

macOS

.dmg, .zip

darwin
🐧

Linux

.flatpak

linux

Manual Download

Browse available releases and download binaries directly for your platform.

Steps

  1. Navigate to the Releases page
  2. Select the version you want to download
  3. Choose the binary for your operating system
  4. Verify the SHA-256 or SHA-512 checksum after download (recommended)
  5. Install and run the application
Verifying Downloads

Each binary includes SHA-256 (hex) and SHA-512 (Base64) hashes for verification. Compare the hash after downloading:

powershell
Get-FileHash -Algorithm SHA256 .\your-app-setup.exe

Auto-Update Setup

Configure your Electron app to automatically check for and install updates using electron-updater.

1. Install Dependencies

bash
npm install electron-updater

2. Configure electron-builder

Add the following configuration to your electron-builder.json or package.json:

json
{
"build": {
"appId": "com.yourcompany.yourapp",
"publish": {
"provider": "generic",
"url": "https://YOUR_DOMAIN/api/update"
}
}
}

3. Main Process Configuration

Add the auto-updater logic to your main process file. The platform and channel parameters are sent automatically:

typescript
1// main.ts or main.js
2import { app, BrowserWindow, ipcMain } from 'electron'
3import { autoUpdater } from 'electron-updater'
4import log from 'electron-log'
5import * as os from 'os'
6
7// Configure logging
8autoUpdater.logger = log
9autoUpdater.logger.transports.file.level = 'info'
10
11// Map Node.js platform to electron-updater format
12const platformMap = {
13 win32: 'win32',
14 darwin: 'darwin',
15 linux: 'linux'
16}
17
18// Configure update server with explicit platform and channel parameters
19autoUpdater.setFeedURL({
20 provider: 'generic',
21 url: `https://YOUR_DOMAIN/api/update?platform=${platformMap[os.platform()] || 'win32'}`,
22 channel: 'stable' // or 'beta', 'alpha'
23})
24
25// Disable auto-download (optional - for manual control)
26autoUpdater.autoDownload = false
27
28// Check for updates on app start
29app.whenReady().then(() => {
30 // Check for updates after 3 seconds
31 setTimeout(() => {
32 autoUpdater.checkForUpdates()
33 }, 3000)
34})
35
36// Auto-updater events
37autoUpdater.on('checking-for-update', () => {
38 log.info('Checking for updates...')
39})
40
41autoUpdater.on('update-available', (info) => {
42 log.info('Update available:', info.version)
43 // Notify renderer process
44 mainWindow?.webContents.send('update-available', info)
45})
46
47autoUpdater.on('update-not-available', () => {
48 log.info('No updates available')
49})
50
51autoUpdater.on('download-progress', (progress) => {
52 log.info(`Download progress: ${progress.percent.toFixed(1)}%`)
53 mainWindow?.webContents.send('download-progress', progress)
54})
55
56autoUpdater.on('update-downloaded', (info) => {
57 log.info('Update downloaded')
58 mainWindow?.webContents.send('update-downloaded', info)
59})
60
61autoUpdater.on('error', (error) => {
62 log.error('Auto-updater error:', error)
63})
64
65// IPC handlers for renderer process control
66ipcMain.handle('check-for-updates', () => {
67 return autoUpdater.checkForUpdates()
68})
69
70ipcMain.handle('download-update', () => {
71 return autoUpdater.downloadUpdate()
72})
73
74ipcMain.handle('install-update', () => {
75 autoUpdater.quitAndInstall(false, true)
76})

4. Renderer Process (React Example)

tsx
1// UpdateNotification.tsx
2import { useEffect, useState } from 'react'
3
4interface UpdateInfo {
5 version: string
6 releaseNotes: string
7}
8
9export function UpdateNotification() {
10 const [updateAvailable, setUpdateAvailable] = useState(false)
11 const [updateInfo, setUpdateInfo] = useState<UpdateInfo | null>(null)
12 const [downloadProgress, setDownloadProgress] = useState(0)
13 const [isDownloading, setIsDownloading] = useState(false)
14 const [isDownloaded, setIsDownloaded] = useState(false)
15
16 useEffect(() => {
17 // Listen for update events from main process
18 window.electron.onUpdateAvailable((info: UpdateInfo) => {
19 setUpdateAvailable(true)
20 setUpdateInfo(info)
21 })
22
23 window.electron.onDownloadProgress((progress: { percent: number }) => {
24 setDownloadProgress(progress.percent)
25 })
26
27 window.electron.onUpdateDownloaded(() => {
28 setIsDownloading(false)
29 setIsDownloaded(true)
30 })
31 }, [])
32
33 const handleDownload = async () => {
34 setIsDownloading(true)
35 await window.electron.downloadUpdate()
36 }
37
38 const handleInstall = () => {
39 window.electron.installUpdate()
40 }
41
42 if (!updateAvailable) return null
43
44 return (
45 <div className="update-notification">
46 <h3>Update Available</h3>
47 <p>Version {updateInfo?.version} is available</p>
48
49 {isDownloading && (
50 <div className="progress-bar">
51 <div style={{ width: `${downloadProgress}%` }} />
52 <span>{downloadProgress.toFixed(1)}%</span>
53 </div>
54 )}
55
56 <div className="actions">
57 {!isDownloaded ? (
58 <button onClick={handleDownload} disabled={isDownloading}>
59 {isDownloading ? 'Downloading...' : 'Download'}
60 </button>
61 ) : (
62 <button onClick={handleInstall}>
63 Install & Restart
64 </button>
65 )}
66 </div>
67 </div>
68 )
69}

API Reference

Complete reference for all available API endpoints.

GET/api/releases
List all releases with pagination
Query Parameters
ParameterTypeDescription
channelstringFilter by channel (stable, beta, alpha)
limitnumberNumber of results (default: 10)
offsetnumberPagination offset (default: 0)
Example Response
json
{
"releases": [
{
"version": "2.1.0",
"channel": "stable",
"changelog": "## What's New\n- Feature A\n- Bug fixes",
"tags": ["breaking"],
"publishedAt": "2024-01-15T10:30:00Z",
"binaries": [
{
"platform": "win32",
"filename": "app-2.1.0-setup.exe",
"size": 85234567,
"sha256": "a1b2c3d4e5...",
"sha512": "XYZ123abc..."
}
]
}
],
"total": 25
}
GET/api/releases/:version
Get details of a specific release
Path Parameters
ParameterTypeDescription
versionstringSemver version (e.g., 2.1.0, 1.0.0-beta.1)
Example Request
bash
curl https://YOUR_DOMAIN/api/releases/2.1.0
GET/api/update/latest.yml
Get the latest release in YAML format (electron-updater standard)
Query Parameters
ParameterTypeDescription
platformstringOptional: win32, darwin, or linux (auto-detected from User-Agent if not provided)
channelstringOptional: stable (default), beta, alpha
Example Request
bash
curl "https://YOUR_DOMAIN/api/update/latest.yml?platform=win32&channel=stable"
Example Response
yaml
version: 2.1.0
files:
- url: app-2.1.0-setup.exe
sha512: abc123...
size: 85234567
path: app-2.1.0-setup.exe
sha512: abc123...
releaseDate: '2024-01-15T10:30:00Z'
releaseNotes: |
## What's New
- Feature A
- Bug fixes

Note: This is the primary endpoint used by electron-updater. The platform parameter should be sent explicitly in the URL for reliable detection.

Release Channels

Use release channels to distribute different versions to different user groups.

stable
Stable
Production-ready releases for all users
beta
Beta
Pre-release testing for early adopters
alpha
Alpha
Experimental builds for internal testing
typescript
// Configure channel in electron-updater
autoUpdater.channel = 'beta' // Switch to beta channel
// Or set via feed URL
autoUpdater.setFeedURL({
provider: 'generic',
url: 'https://YOUR_DOMAIN/api/update/latest?channel=beta'
})

Integrity Verification

All binaries include both SHA-256 and SHA-512 checksums for integrity verification. Electron-updater automatically validates downloads using SHA-512 in Base64 format.

Note: The platform uses SHA-512 in Base64 format for electron-updater compatibility, and SHA-256 in hexadecimal for manual verification.

Manual SHA-256 Verification

typescript
1// Verify download integrity using SHA-256 (manual verification)
2import crypto from 'crypto'
3import fs from 'fs'
4
5async function verifySHA256(filePath: string, expectedHash: string): Promise<boolean> {
6 return new Promise((resolve, reject) => {
7 const hash = crypto.createHash('sha256')
8 const stream = fs.createReadStream(filePath)
9
10 stream.on('data', (data) => hash.update(data))
11 stream.on('end', () => {
12 const calculatedHash = hash.digest('hex')
13 resolve(calculatedHash === expectedHash)
14 })
15 stream.on('error', reject)
16 })
17}
18
19// Usage
20const isValid = await verifySHA256('./app-setup.exe', 'expected-sha256-hash-in-hex')
21if (!isValid) {
22 throw new Error('File integrity check failed!')
23}

SHA-512 Verification (electron-updater format)

typescript
1// Verify using SHA-512 in Base64 (same format as electron-updater)
2import crypto from 'crypto'
3import fs from 'fs'
4
5async function verifySHA512Base64(filePath: string, expectedHash: string): Promise<boolean> {
6 return new Promise((resolve, reject) => {
7 const hash = crypto.createHash('sha512')
8 const stream = fs.createReadStream(filePath)
9
10 stream.on('data', (data) => hash.update(data))
11 stream.on('end', () => {
12 const calculatedHash = hash.digest('base64')
13 resolve(calculatedHash === expectedHash)
14 })
15 stream.on('error', reject)
16 })
17}
18
19// Usage
20const isValid = await verifySHA512Base64('./app-setup.exe', 'expected-sha512-base64')
21if (!isValid) {
22 throw new Error('SHA-512 integrity check failed!')
23}

Tip: electron-updater performs SHA-512 verification automatically. Manual verification is only needed if downloading files outside the auto-update flow.

Troubleshooting

Common issues and their solutions.

Update check fails with network error

Ensure your app has internet access and the update server URL is correct.

typescript
// Enable detailed logging
import log from 'electron-log'
autoUpdater.logger = log
autoUpdater.logger.transports.file.level = 'debug'
Update downloaded but won't install

On Windows, ensure the app is code-signed. On macOS, check Gatekeeper settings.

typescript
// Force quit and install
autoUpdater.quitAndInstall(
false, // isSilent
true // isForceRunAfter
)
CORS errors when checking for updates

The update server should return proper CORS headers. Check your server configuration.

json
{
"headers": {
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, OPTIONS"
}
}