From 60f441746f6b13d7d8a378305f14ed16b9923345 Mon Sep 17 00:00:00 2001 From: "electron-website-docs-updater[bot]" <166660481+electron-website-docs-updater[bot]@users.noreply.github.com> Date: Tue, 24 Sep 2024 21:36:55 +0000 Subject: [PATCH] =?UTF-8?q?chore:=20update=20ref=20to=20docs=20(?= =?UTF-8?q?=F0=9F=A4=96)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/latest/api/auto-updater.md | 26 +++++++++------- docs/latest/tutorial/updates.md | 54 ++++++++++++++++++++++++++++++++- 2 files changed, 68 insertions(+), 12 deletions(-) diff --git a/docs/latest/api/auto-updater.md b/docs/latest/api/auto-updater.md index ea93dba..195fa6d 100644 --- a/docs/latest/api/auto-updater.md +++ b/docs/latest/api/auto-updater.md @@ -39,22 +39,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: @@ -144,9 +150,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 diff --git a/docs/latest/tutorial/updates.md b/docs/latest/tutorial/updates.md index 99bb27a..6affb7b 100644 --- a/docs/latest/tutorial/updates.md +++ b/docs/latest/tutorial/updates.md @@ -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