docs: add advanced specification for Squirrel updater (#43891)
* 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]
GitHub
parent
8b229743d5
commit
19b70a4cb4
2 changed files with 68 additions and 12 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue