electron/docs/api/auto-updater.md

118 lines
3.6 KiB
Markdown
Raw Normal View History

2015-08-19 16:55:11 +00:00
# autoUpdater
2013-08-14 22:43:35 +00:00
2016-04-21 22:39:12 +00:00
> Enable apps to update themselves automatically.
The `autoUpdater` module provides and interface for the [Squirrel](https://github.com/Squirrel) framework.
You can quickly launch a multi-platform release server for distributing your
application by using one of these projects:
- [electron-release-server][electron-release-server]: *A fully featured,
self-hosted release server for electron applications, compatible with
auto-updater*
- [squirrel-updates-server][squirrel-updates-server]: *A simple node.js server
for Squirrel.Mac and Squirrel.Windows which uses GitHub releases*
2015-10-23 12:11:59 +00:00
## Platform notices
Though `autoUpdater` provides a uniform API for different platforms, there are
2015-10-23 12:11:59 +00:00
still some subtle differences on each platform.
2015-10-23 12:11:59 +00:00
### OS X
On OS X, the `autoUpdater` module is built upon [Squirrel.Mac][squirrel-mac],
meaning you don't need any special setup to make it work. For server-side
requirements, you can read [Server Support][server-support].
**Note:** Your application must be signed for automatic updates on Mac OS X.
This is a requirement of `Squirrel.Mac`.
2015-10-23 12:11:59 +00:00
### Windows
On Windows, you have to install your app into a user's machine before you can
use the auto-updater, so it is recommended to use
[grunt-electron-installer][installer] module to generate a Windows installer.
The installer generated with Squirrel 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.
The server-side setup is also different from OS X. You can read the documents of
2015-10-23 12:11:59 +00:00
[Squirrel.Windows][squirrel-windows] to get more details.
2015-10-23 12:11:59 +00:00
### Linux
2015-12-14 00:02:30 +00:00
There is no built-in support for auto-updater on Linux, so it is recommended to
2015-10-23 12:11:59 +00:00
use the distribution's package manager to update your app.
2015-08-19 16:55:11 +00:00
## Events
The `autoUpdater` object emits the following events:
### Event: 'error'
Returns:
2015-10-23 06:36:36 +00:00
* `error` Error
Emitted when there is an error while updating.
2015-08-19 16:55:11 +00:00
### Event: 'checking-for-update'
2013-08-14 22:43:35 +00:00
2015-07-28 15:51:41 +00:00
Emitted when checking if an update has started.
2013-08-14 22:43:35 +00:00
2015-08-19 16:55:11 +00:00
### Event: 'update-available'
Emitted when there is an available update. The update is downloaded
automatically.
2015-08-19 16:55:11 +00:00
### Event: 'update-not-available'
2013-08-14 22:43:35 +00:00
Emitted when there is no available update.
2013-08-14 22:43:35 +00:00
2015-08-19 16:55:11 +00:00
### Event: 'update-downloaded'
Returns:
2013-08-14 22:43:35 +00:00
* `event` Event
* `releaseNotes` String
* `releaseName` String
* `releaseDate` Date
2015-11-13 08:03:40 +00:00
* `updateURL` String
2013-08-14 22:43:35 +00:00
2015-10-23 07:50:55 +00:00
Emitted when an update has been downloaded.
2013-08-14 22:43:35 +00:00
2015-10-23 12:11:59 +00:00
On Windows only `releaseName` is available.
2015-08-19 16:55:11 +00:00
## Methods
The `autoUpdater` object has the following methods:
2015-11-13 08:03:40 +00:00
### `autoUpdater.setFeedURL(url)`
2013-08-14 22:43:35 +00:00
* `url` String
2015-10-23 07:50:55 +00:00
Sets the `url` and initialize the auto updater. The `url` cannot be changed
once it is set.
2013-08-14 22:43:35 +00:00
2015-08-19 16:55:11 +00:00
### `autoUpdater.checkForUpdates()`
2013-08-14 22:43:35 +00:00
2015-11-13 08:03:40 +00:00
Asks the server whether there is an update. You must call `setFeedURL` before
using this API.
2015-10-23 07:50:55 +00:00
### `autoUpdater.quitAndInstall()`
2015-10-23 07:50:55 +00:00
Restarts the app and installs the update after it has been downloaded. It
should only be called after `update-downloaded` has been emitted.
2015-10-23 12:11:59 +00:00
[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
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx
[electron-release-server]: https://github.com/ArekSredzki/electron-release-server
[squirrel-updates-server]: https://github.com/Aluxian/squirrel-updates-server