2015-08-19 16:55:11 +00:00
# autoUpdater
2013-08-14 22:43:35 +00:00
2016-04-22 18:42:54 +00:00
> Enable apps to automatically update themselves.
2016-04-21 22:35:29 +00:00
2016-11-23 19:20:56 +00:00
Process: [Main ](../glossary.md#main-process )
2016-11-03 17:26:00 +00:00
2017-08-11 23:10:20 +00:00
**You can find a detailed guide about how to implement updates into your application [here ](../tutorial/updates.md ).**
2016-03-22 23:35:03 +00:00
2015-10-23 12:11:59 +00:00
## Platform notices
2014-05-05 02:07:15 +00:00
2017-08-11 23:10:20 +00:00
Although `autoUpdater` provides a uniform API for different platforms, there are
still some subtle differences on each platform:
2014-05-05 02:07:15 +00:00
2016-06-18 13:26:26 +00:00
### macOS
2014-07-25 16:14:49 +00:00
2016-06-18 13:26:26 +00:00
On macOS, the `autoUpdater` module is built upon [Squirrel.Mac][squirrel-mac],
2015-11-03 07:30:54 +00:00
meaning you don't need any special setup to make it work. For server-side
2016-11-10 18:35:56 +00:00
requirements, you can read [Server Support][server-support]. Note that [App
Transport Security](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW35) (ATS) applies to all requests made as part of the
update process. Apps that need to disable ATS can add the
`NSAllowsArbitraryLoads` key to their app's plist.
2014-05-05 02:07:15 +00:00
2016-06-18 13:26:26 +00:00
**Note:** Your application must be signed for automatic updates on macOS.
2016-04-07 00:40:07 +00:00
This is a requirement of `Squirrel.Mac` .
2015-10-23 12:11:59 +00:00
### Windows
2014-05-05 02:07:15 +00:00
2015-11-03 07:30:54 +00:00
On Windows, you have to install your app into a user's machine before you can
2016-05-06 17:05:12 +00:00
use the `autoUpdater` , so it is recommended that you use the
2017-06-26 05:10:48 +00:00
[electron-winstaller][installer-lib], [electron-forge][electron-forge-lib] or the [grunt-electron-installer][installer] package to generate a Windows installer.
2015-11-03 07:30:54 +00:00
2017-06-26 05:10:48 +00:00
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.
2016-09-09 18:51:42 +00:00
2015-11-03 07:30:54 +00:00
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.
2014-05-05 02:07:15 +00:00
2017-06-26 05:10:48 +00:00
Unlike 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.
2014-05-05 02:07:15 +00:00
2015-10-23 12:11:59 +00:00
### Linux
2014-05-05 02:07:15 +00:00
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-30 22:07:36 +00:00
2015-08-19 16:55:11 +00:00
## Events
The `autoUpdater` object emits the following events:
### Event: 'error'
Returns:
2015-04-07 16:21:29 +00:00
2015-10-23 06:36:36 +00:00
* `error` Error
2015-04-07 16:21:29 +00:00
2015-07-23 16:57:42 +00:00
Emitted when there is an error while updating.
2015-04-07 16:21:29 +00:00
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'
2014-02-02 12:37:46 +00:00
2015-07-23 16:57:42 +00:00
Emitted when there is an available update. The update is downloaded
2014-02-02 12:37:46 +00:00
automatically.
2015-08-19 16:55:11 +00:00
### Event: 'update-not-available'
2013-08-14 22:43:35 +00:00
2014-02-02 12:37:46 +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
2014-02-02 12:37:46 +00:00
* `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:
2016-06-10 13:55:42 +00:00
### `autoUpdater.setFeedURL(url[, requestHeaders])`
2013-08-14 22:43:35 +00:00
* `url` String
2016-10-30 10:46:20 +00:00
* `requestHeaders` Object _macOS_ (optional) - HTTP request headers.
2013-08-14 22:43:35 +00:00
2016-06-10 13:55:42 +00:00
Sets the `url` and initialize the auto updater.
2013-08-14 22:43:35 +00:00
2016-07-14 12:07:17 +00:00
### `autoUpdater.getFeedURL()`
2016-09-24 23:59:30 +00:00
Returns `String` - The current update feed URL.
2016-07-14 12:07:17 +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
2014-02-02 12:37:46 +00:00
using this API.
2015-10-23 07:50:55 +00:00
2015-10-30 11:17:30 +00:00
### `autoUpdater.quitAndInstall()`
2015-10-23 07:50:55 +00:00
2015-11-03 07:30:54 +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
2016-11-16 09:35:02 +00:00
**Note:** `autoUpdater.quitAndInstall()` will close all application windows
first and only emit `before-quit` event on `app` after that. This is different
from the normal quit event sequence.
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
2016-05-06 17:05:12 +00:00
[installer]: https://github.com/electron/grunt-electron-installer
[installer-lib]: https://github.com/electron/windows-installer
2017-06-26 05:10:48 +00:00
[electron-forge-lib]: https://github.com/electron-userland/electron-forge
2015-11-03 07:30:54 +00:00
[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx