docs: auto-updater on Windows
This commit is contained in:
Cheng Zhao
parent
fae2c7bc7a
commit
88b05cff3e
1 changed files with 24 additions and 92 deletions
|
|
@ -1,106 +1,31 @@
|
|||
# autoUpdater
|
||||
|
||||
**This module has only been implemented for OS X.**
|
||||
This module provides an interface for the `Squirrel` auto-updater framework.
|
||||
|
||||
Check out [atom/grunt-electron-installer](https://github.com/atom/grunt-electron-installer)
|
||||
to build a Windows installer for your app.
|
||||
## Platform notices
|
||||
|
||||
The `auto-updater` module is a simple wrapper around the
|
||||
[Squirrel.Mac](https://github.com/Squirrel/Squirrel.Mac) framework.
|
||||
Though `autoUpdater` provides an uniform API for different platforms, there are
|
||||
still some subtle differences on each platform.
|
||||
|
||||
Squirrel.Mac requires that your `.app` folder is signed using the
|
||||
[codesign](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/codesign.1.html)
|
||||
utility for updates to be installed.
|
||||
### OS X
|
||||
|
||||
## Squirrel
|
||||
On OS X the `autoUpdater` module is built upon [Squirrel.Mac][squirrel-mac], you
|
||||
don't need any special setup to make it work. For server-side requirements, you
|
||||
can read [Server Support][server-support].
|
||||
|
||||
Squirrel is an OS X framework focused on making application updates **as safe
|
||||
and transparent as updates to a website**.
|
||||
### Windows
|
||||
|
||||
Instead of publishing a feed of versions from which your app must select,
|
||||
Squirrel updates to the version your server tells it to. This allows you to
|
||||
intelligently update your clients based on the request you give to Squirrel.
|
||||
On Windows you have to install your app into user's machine before you can use
|
||||
the auto-updater, it is recommended to use [grunt-electron-installer][installer]
|
||||
module to generate a Windows installer.
|
||||
|
||||
Your request can include authentication details, custom headers or a request
|
||||
body so that your server has the context it needs in order to supply the most
|
||||
suitable update.
|
||||
The server-side setup is also different from OS X, you can read the documents of
|
||||
[Squirrel.Windows][squirrel-windows] to get more details.
|
||||
|
||||
The update JSON Squirrel requests should be dynamically generated based on
|
||||
criteria in the request and whether an update is required. Squirrel relies
|
||||
on server-side support to determine whether an update is required. See
|
||||
[Server Support](#server-support).
|
||||
### Linux
|
||||
|
||||
Squirrel's installer is designed to be fault tolerant and ensures that any
|
||||
updates installed are valid.
|
||||
|
||||
## Update Requests
|
||||
|
||||
Squirrel is indifferent to the request the client application provides for
|
||||
update checking. `Accept: application/json` is added to the request headers
|
||||
because Squirrel is responsible for parsing the response.
|
||||
|
||||
For the requirements imposed on the responses and the body format of an update
|
||||
response, see [Server Support](#server-support).
|
||||
|
||||
Your update request must *at least* include a version identifier so that the
|
||||
server can determine whether an update for this specific version is required. It
|
||||
may also include other identifying criteria, such as operating system version or
|
||||
username, to allow the server to deliver as fine grained an update as you
|
||||
would like.
|
||||
|
||||
How you include the version identifier or other criteria is specific to the
|
||||
server that you are requesting updates from. A common approach is to use query
|
||||
parameters, like this:
|
||||
|
||||
```javascript
|
||||
// In the main process
|
||||
var app = require('app');
|
||||
var autoUpdater = require('auto-updater');
|
||||
autoUpdater.setFeedUrl('http://mycompany.com/myapp/latest?version=' + app.getVersion());
|
||||
```
|
||||
|
||||
## Server Support
|
||||
|
||||
Your server should determine whether an update is required based on the
|
||||
[Update Request](#update-requests) your client issues.
|
||||
|
||||
If an update is required, your server should respond with a status code of
|
||||
[200 OK](http://tools.ietf.org/html/rfc2616#section-10.2.1) and include the
|
||||
[update JSON](#update-json-format) in the body. Squirrel **will** download and
|
||||
install this update, even if the version of the update is the same as the
|
||||
currently running version. To save redundantly downloading the same version
|
||||
multiple times your server must not inform the client to update.
|
||||
|
||||
If no update is required your server must respond with a status code of
|
||||
[204 No Content](http://tools.ietf.org/html/rfc2616#section-10.2.5). Squirrel
|
||||
will check for an update again at the interval you specify.
|
||||
|
||||
## Update JSON Format
|
||||
|
||||
When an update is available, Squirrel expects the following schema in response
|
||||
to the update request provided:
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "http://mycompany.com/myapp/releases/myrelease",
|
||||
"name": "My Release Name",
|
||||
"notes": "Theses are some release notes innit",
|
||||
"pub_date": "2013-09-18T12:29:53+01:00"
|
||||
}
|
||||
```
|
||||
|
||||
The only required key is "url"; the others are optional.
|
||||
|
||||
Squirrel will request "url" with `Accept: application/zip` and only supports
|
||||
installing ZIP updates. If future update formats are supported their MIME type
|
||||
will be added to the `Accept` header so that your server can return the
|
||||
appropriate format.
|
||||
|
||||
`pub_date` (if present) must be formatted according to ISO 8601.
|
||||
|
||||
## Update server implementations
|
||||
|
||||
[Nuts](https://github.com/GitbookIO/nuts) is an open source implementation of the update server described above, it integrates beautifully with GitHub releases. Nuts manages downloads and updates, it’s compatible with `Squirrel.Mac` and `Squirrel.Windows` so you get cross-platform support out of the box.
|
||||
There is not built-in support for auto-updater on Linux, it is recommended to
|
||||
use the distribution's package manager to update your app.
|
||||
|
||||
## Events
|
||||
|
||||
|
|
@ -139,6 +64,8 @@ Returns:
|
|||
|
||||
Emitted when an update has been downloaded.
|
||||
|
||||
On Windows only `releaseName` is available.
|
||||
|
||||
## Methods
|
||||
|
||||
The `autoUpdater` object has the following methods:
|
||||
|
|
@ -159,3 +86,8 @@ using this API.
|
|||
|
||||
Restarts the app and install the update after it has been downloaded. It should
|
||||
only be called after `update-downloaded` has been emitted.
|
||||
|
||||
[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/atom/grunt-electron-installer
|
||||
|
|
|
|||
Loading…
Reference in a new issue