mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add advanced specification for Squirrel updater (#43891)

Browse source 
* docs: add advanced specification for Squirrel updater

Co-authored-by: Erick Zhao <ezhao@slack-corp.com>

* address feedback

Co-authored-by: Erick Zhao <ezhao@slack-corp.com>

---------

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Erick Zhao <ezhao@slack-corp.com>
This commit is contained in:
trop[bot] 2024-09-23 11:02:31 -07:00 committed by GitHub
parent 8b229743d5
commit 19b70a4cb4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 68 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
docs/api/auto-updater.md
View file

@ -32,22 +32,28 @@ This is a requirement of `Squirrel.Mac`.
### Windows
On Windows, you have to install your app into a user's machine before you can
use the `autoUpdater`, so it is recommended that you use the
[electron-winstaller][installer-lib], [Electron Forge][electron-forge-lib] or the [grunt-electron-installer][installer] package to generate a Windows installer.
use the `autoUpdater`, so it is recommended that you use
[electron-winstaller][installer-lib] or [Electron Forge's Squirrel.Windows maker][electron-forge-lib] to generate a Windows installer.
When using [electron-winstaller][installer-lib] or [Electron Forge][electron-forge-lib] make sure you do not try to update your app [the first time it runs](https://github.com/electron/windows-installer#handling-squirrel-events) (Also see [this issue for more info](https://github.com/electron/electron/issues/7155)). It's also recommended to use [electron-squirrel-startup](https://github.com/mongodb-js/electron-squirrel-startup) to get desktop shortcuts for your app.
Apps built with Squirrel.Windows will trigger [custom launch events](https://github.com/Squirrel/Squirrel.Windows/blob/51f5e2cb01add79280a53d51e8d0cfa20f8c9f9f/docs/using/custom-squirrel-events-non-cs.md#application-startup-commands)
that must be handled by your Electron application to ensure proper setup and teardown.
The installer generated with Squirrel will create a shortcut icon with an
Squirrel.Windows apps will launch with the `--squirrel-firstrun` argument immediately
after installation. During this time, Squirrel.Windows will obtain a file lock on
your app, and `autoUpdater` requests will fail until the lock is released. In practice,
this means that you won't be able to check for updates on first launch for the first
few seconds. You can work around this by not checking for updates when `process.argv`
contains the `--squirrel-firstrun` flag or by setting a 10-second timeout on your
update checks (see [electron/electron#7155](https://github.com/electron/electron/issues/7155)
for more information).
The installer generated with Squirrel.Windows will create a shortcut icon with an
[Application User Model ID][app-user-model-id] in the format of
`com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE`, examples are
`com.squirrel.slack.Slack` and `com.squirrel.code.Code`. You have to use the
same ID for your app with `app.setAppUserModelId` API, otherwise Windows will
not be able to pin your app properly in task bar.
Like Squirrel.Mac, Windows can host updates on S3 or any other static file host.
You can read the documents of [Squirrel.Windows][squirrel-windows] to get more details
about how Squirrel.Windows works.
## Events
The `autoUpdater` object emits the following events:
@ -137,9 +143,7 @@ application starts.
[squirrel-mac]: https://github.com/Squirrel/Squirrel.Mac
[server-support]: https://github.com/Squirrel/Squirrel.Mac#server-support
[squirrel-windows]: https://github.com/Squirrel/Squirrel.Windows
[installer]: https://github.com/electron-archive/grunt-electron-installer
[installer-lib]: https://github.com/electron/windows-installer
[electron-forge-lib]: https://github.com/electron/forge
[electron-forge-lib]: https://www.electronforge.io/config/makers/squirrel.windows
[app-user-model-id]: https://learn.microsoft.com/en-us/windows/win32/shell/appids
[event-emitter]: https://nodejs.org/api/events.html#events_class_eventemitter

54
docs/tutorial/updates.md
View file

@ -261,7 +261,59 @@ server-communication aspect of the process by loading your update from a local d
## Update server specification
A Squirrel-compatible update server has different
For advanced deployment needs, you can also roll out your own Squirrel-compatible update server.
For example, you may want to have percentage-based rollouts, distribute your app through separate
release channels, or put your update server behind an authentication check.
Squirrel.Windows and Squirrel.Mac clients require different response formats,
but you can use a single server for both platforms by sending requests to
different endpoints depending on the value of `process.platform`.
```js title='main.js'
const { app, autoUpdater } = require('electron')
const server = 'https://your-deployment-url.com'
// e.g. for Windows and app version 1.2.3
// https://your-deployment-url.com/update/win32/1.2.3
const url = `${server}/update/${process.platform}/${app.getVersion()}`
autoUpdater.setFeedURL({ url })
```
### Windows
A Squirrel.Windows client expects the update server to return the `RELEASES` artifact
of the latest available build at the `/RELEASES` subpath of your endpoint.
For example, if your feed URL is `https://your-deployment-url.com/update/win32/1.2.3`,
then the `https://your-deployment-url.com/update/win32/1.2.3/RELEASES` endpoint
should return the contents of the `RELEASES` artifact of the version you want to serve.
```plaintext title='https://your-deployment-url.com/update/win32/1.2.3/RELEASES'
B0892F3C7AC91D72A6271FF36905FEF8FE993520 https://your-static.storage/your-app-1.2.3-full.nupkg 103298365
```
Squirrel.Windows does the comparison check to see if the current app should update to
the version returned in `RELEASES`, so you should return a response even when no update
is available.
### macOS
When an update is available, the Squirrel.Mac client expects a JSON response at the feed URL's endpoint.
This object has a mandatory `url` property that maps to a ZIP archive of the
app update. All other properties in the object are optional.
```json title='https://your-deployment-url.com/update/darwin/0.31.0'
{
"url": "https://your-static.storage/your-app-1.2.3-darwin.zip",
"name": "1.2.3",
"notes": "Theses are some release notes innit",
"pub_date": "2024-09-18T12:29:53+01:00"
}
```
If no update is available, the server should return a [`204 No Content`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204)
HTTP response.
[vercel]: https://vercel.com
[hazel]: https://github.com/vercel/hazel