User Feedback

Let’s update those event handlers to provide some feedback to the user about the auto-update process. These dialogs should be familiar to you from the earlier chapter on dialogs.

const dialog = electron.dialog

autoUpdater.addListener("update-available", function (event) {
  console.log('Update Available')
  dialog.showMessageBox({
    type: "info",
    title: "Update Available",
    message: 'There is an update available.' + appVersion,
    buttons: ["Update", "Skip"]
  }, function (index) {
    console.log(index)
  })
})

autoUpdater.addListener("update-downloaded", function (event, releaseNotes, releaseName, releaseDate, updateURL) {
  console.log('releaseNotes', "Update Downloaded")
  console.log('releaseNotes', releaseNotes)
  console.log('releaseNotes', releaseName)
  console.log('releaseNotes', releaseDate)
  console.log('releaseNotes', updateURL)

  dialog.showMessageBox({
    type: "info",
    title: "Update Downloaded",
    message: "Update has downloaded",
    detail: releaseNotes,
    buttons: ["Install", "Skip"]
  }, function (index) {
    if (index === 0) {
      autoUpdater.quitAndInstall()
    }
    autoUpdater.quitAndInstall()
  })
})

autoUpdater.addListener("error", function (error) {
  console.log('Error')
  console.log(error)
  dialog.showMessageBox({
    type: "warning",
    title: "Update Error",
    message: 'An error occurred. ' + error,
    buttons: ["OK"]
  })
})

autoUpdater.addListener("checking-for-update", function (event) {
  console.log('releaseNotes', 'Checking for Update')
})

autoUpdater.addListener("update-not-available", function (event) {
  console.log('releaseNotes', 'Update Not Available')
  dialog.showMessageBox({
    type: "warning",
    title: "No Updates",
    message: 'No update available at this time.',
    buttons: ["OK"]
  })
})

You will probably want to adjust these for a better user experience.

Auto Update Server Options

There are several prebuilt solutions available for you to use. The Auto Update module’s documentation lists these as options:

• nuts: A smart release server for your applications, using GitHub as a back end. Auto updates with Squirrel (Mac & Windows). [ https://github.com/GitbookIO/nuts ]

• electron-release-server: A fully featured, self-hosted release server for electron applications, compatible with auto updater. [ https://github.com/ArekSredzki/electron-release-server ]

• squirrel-updates-server: A simple node.js server for Squirrel.Mac and Squirrel.Windows that uses GitHub releases. [ https://github.com/Aluxian/squirrel-updates-server ]

• squirrel-release-server: A simple PHP application for Squirrel.Windows that reads updates from a folder. Supports delta updates. [ https://github.com/Arcath/squirrel-release-server ]

However, there is not too much to the server-side code, so let’s set up our own server using Heroku. Now, this is completely optional; so if you are comfortable working with servers, then please feel free to skip to the next section.

'use strict'
const fs = require('fs')
const express = require('express')
const path = require('path')
const app = express()

app.get('/updates/latest', function (req, res) {
    const latest = getLatestRelease()
    const clientVersion = req.query.v

    if (clientVersion === latest) {
        res.status(204).end()
    } else {
        let baseURL = getBaseUrl()
        let updateURL = baseURL + '/releases/darwin/' + latest + '/electron.zip'

       res.json({
            url: updateURL,
            name: "My Release Name",
            notes: "These are some release notes",
            pub_date: "2017-04-18T12:29:53+01:00"

        })
    }
})

let getLatestRelease = () => {
    const dir = __dirname + '/releases/darwin'

    const versionsDesc = fs.readdirSync(dir).filter((file) => {
        const filePath = path.join(dir, file)
        return fs.statSync(filePath).isDirectory()
    }).reverse()

    return versionsDesc[0];
}

let getBaseUrl = () => {
  if (process.env.NODE_ENV === 'development') {
    return 'http://localhost:3000'
  } else {
    return 'http://your-company.com'
  }
}

app.listen(process.env.PORT || 3000, () => {
  console.log(`Express server listening on port ${process.env.PORT || 3000}`)
});

Testing Our Auto Update

Once you have deployed your server code to Heroku, let’s test it in our browser. Simply go to https://<your=app-name>.herokuapp.com/updates/latest?v=1.0.0

and you should see the following in the window:

{"url":"http://your-company.com/releases/darwin/1.0.0/electron.zip","name":"My Release Name","notes":"These are some release notes","pub_date":"2017-04-18T12:29:53+01:00"}

This means our server is running and responding properly. We can now return to our Electron code and complete the changes we need to make.

Signing Your Application

To have auto updating function properly, our Electron applications need to be signed. Otherwise, the auto-updating mechanism will not function. For self-distributed apps and testing, we can generate our own certificate by using the Keychain Access tool, found in the /Applications/Utilities directory.

Create new certificate:

Keychain Access ➤ Certificate Assistant ➤ Create a Certificate…

Give your certificate a name and select Code Signing as the Certificate Type. Next, we need to set the trust level. To do this, locate the newly created certificate in the panel, and double-click to open it. Then change the When using this certificate to Always Trust. This will allow our Electron application to be properly signed.

We need to now set the CSC_NAME environment variable, so the signing can occur when we build our application. In your terminal and in our application’s active directory, run

export CSC_NAME="Certificate Name"

Now, when we build our application it will be signed and auto updating will function.

If you are planning to distribute through the macOS store, you will need a signing certificate from Apple. For more on this process see: https://github.com/electron/electron/blob/master/docs/tutorial/mac-app-store-submission-guide.md

Building the Application - macOS

With our update server in place and running, and our signing certificate generated and installed, we are ready to build the first version of our app. In the main.js file, you will need to update the updateURL variable to reflect your Heroku server before proceeding. To reduce our build times, let’s only build for macOS. Adjust the dist script in the package.json file to:

"dist": "build -m"

Now, let’s build our application.

npm run dist

After a few moments, we should have our .dmg file, our .app file, as well as out .zip of our application. Go ahead and run the application. Once it launches, the Auto Update module will ping our server. Since we only have version 1.0.0 of our app, it will report back that there is no update (Figure 16-1).

Figure 16-1. Our app informing the user that no update is available

Generating an Update

To generate an update, we need to do three things. First, build a new version of the application with a new version number. To do this, we just need to change the version number in our package.json file:

"version": "1.0.1"

Then, just rebuild our app. Although we did not make any code changes, the app will still respond as version 1.0.1.

Second, we need to upload our new build to where we store the application.

Third, we need to update our Heroku server to respond correctly based on the proper version number. Just duplicate our 1.0.0 directory and rename it to match our app’s new version. Then upload the new structure to Heroku, and have the server restart.

With all three steps complete, go ahead and run the app. After a few moments, the app should inform you that an update is available (Figure 16-2).

Figure 16-2. The Auto Update module has detected an update

Click the Update button to update the application (Figure 16-3).

Figure 16-3. The Auto Update module has downloaded the update and is ready to apply it

The app will automatically quit and then relaunch. With that, we have a working auto-update system for our macOS Electron applications.

Signing Your Windows Application

Like building auto-updating apps for macOS, Windows apps must also be signed. Otherwise, anti-virus/malware scanners might flag your application, or Windows SmartScreen may require special actions to enable to run it. We doubt this is the user experience you want. There are a variety of third-party certificate vendors that can issue you a certificate that will allow you to formally sign your application. Unfortunately, these options are not free. Thankfully, there is a method to generate your own certificate for development and testing purposes. If you plan to release your application to the public, you will need to formally sign your application.

To generate your own .pfx file, which Electron Builder uses to sign your application, you will need to use OpenSSL. What is OpenSSL, from their website:

OpenSSL is an open source project that provides a robust, commercial-grade, and full-featured toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols.

If you are building your application on a macOS computer, OpenSSL is already installed. If you are building your Electron application on a Windows computer, you will need to download an installer from https://wiki.openssl.org/index.php/Binaries .

To generate our *.pfx file, we need to first generate a private key and certificate. OpenSSL will allow us to do all three steps. With OpenSSL installed, and then launch your terminal to first generate our private key:

openssl genrsa -aes128 -out privateKey.key 2048

You will be prompted to enter a passphrase for the key. Enter something that you will remember, and store it in a safe place. This information cannot be recovered.

Next, we can use that key to generate our certificate:

openssl req -new -x509 -days 365 -key privateKey.key -out certificate.crt

It will prompt you to enter the passphrase you just created for the key file. It will then ask you a series of questions that it will use to identify the certificate. Here is a sample of those questions.

You are about to be asked to enter information that will be incorporated

into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:YORU COUNTRY
State or Province Name (full name) [Some-State]:YOUR STATE
Locality Name (eg, city) []:YOUR CITY
Organization Name (eg, company) [Internet Widgits Pty Ltd]:YOUR COMPANY
Organizational Unit Name (eg, section) []:YOUR UNIT
Common Name (e.g. server FQDN or YOUR name) []:YOUR NAME
Email Address []:[email protected]

Now, with our private key and certificate generated, we can combine them into a .pfx file by using this command:

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt

You will once again be prompted for the passphrase for your privateKey. Then you will be asked for the password that will be used to unlock the pfx file. Safely store all three files, as they are uniquely generated. With our pfx file created, we can modify the package.json to enable signing of our Windows application. We place our *.pfx file in a cert directory within our general development directory. Set the certificateFile to the location of the *.pfx file, and the certificatePassword to the export password.

"win": {
      "target": [
        "squirrel"
      ],
      "certificateFile": "./certificate.pfx",
      "certificatePassword": "your-password",
      "icon": "./build/icon.ico"
    },

Customizing the Squirrel Installer

Unlike the NSIS installer, using the Squirrel installer actually has very few configurations. The first item we can set is the icon for the generated setup.exe file. Typically, this will be the same as your application’s icon. But unlike, the application icon, the location of this file must be remotely hosted. We typically place it in the same directory that we stored the Windows updates.

"squirrelWindows": {
      "iconUrl": "http://your-company.com/releases/win/icon.ico",
  }

Next, we can modify the loading animation that is displayed by Squirrel as it silently installs your application. The default image looks like Figure 16-4, albeit animated.

Figure 16-4. Default Squirrel Loading GIF

You can easily replace with your own gif file. Simply set the loadingGif to a file. You do not need to have this image be animated.

"squirrelWindows": {
      "iconUrl": "http://your-company.com/releases/win/icon.ico",
      "loadingGif": "./build/loader.gif"
 }

The next item to adjust is a subtle one. When Squirrel installs your application, it places it within the AppData directory. It will create a new directory based either on your app ID or the name attribute. When Squirrel creates the folder to install your application, and by default it will use your app ID. However, since your app ID will probably follow the pattern of com.company-name.app-name, Windows will truncate the directory name to just com. Instead, we recommend using your name attribute instead. To do this, add useAppIdAsId and set it to false.

"squirrelWindows": {
      "iconUrl": "http://your-company.com/releases/win/icon.ico",
      "loadingGif": "./build/loader.gif",
      "useAppIdAsId": false
    }

This will now enable us to build our Windows application, but we need to make some additional changes to the main.js file to support auto updating with Squirrel. First, we need to set a new updateURL to check for any updates. Here is the new code block for this.

if (process.platform === 'darwin') {
  autoUpdater.setFeedURL(updateUrl)
  autoUpdater.checkForUpdates()
} else {
  updateUrl = "http://your-company.com/releases/win/"
  autoUpdater.setFeedURL(updateUrl)
  autoUpdater.checkForUpdates()
}

Since our app is now dependent on Squirrel to manage itself, we need to properly handle those events before our application creates its window. These events center around the various installation or uninstall steps that might need to occur. Here is a complete code sample that handles each of the Squirrel events that should be added to the main.js file:

if (handleSquirrelEvent()) {
  // squirrel event handled and app will exit in 1000ms, so don't do anything else
  return
}

function handleSquirrelEvent() {
  if (process.argv.length === 1) {
    return false
  }

  const ChildProcess = require('child_process')
  const path = require('path')

  const appFolder = path.resolve(process.execPath, '..')
  const rootAtomFolder = path.resolve(appFolder, '..')
  const updateDotExe = path.resolve(path.join(rootAtomFolder, 'Update.exe'))
  const exeName = path.basename(process.execPath)

  const spawn = function (command, args) {
    let spawnedProcess, error

    try {
      spawnedProcess = ChildProcess.spawn(command, args, { detached: true })
    } catch (error) { }

    return spawnedProcess
  }

  const spawnUpdate = function (args) {
    return spawn(updateDotExe, args)
  }

  const squirrelEvent = process.argv[1]
  switch (squirrelEvent) {
    case '--squirrel-install':
    case '--squirrel-updated':
      // Optionally do things such as:
      // - Add your .exe to the PATH
      // - Write to the registry for things like file associations and
      //   explorer context menus

      // Install desktop and start menu shortcuts
      spawnUpdate(['--createShortcut', exeName])

      setTimeout(app.quit, 1000)
      return true

    case '--squirrel-uninstall':
      // Undo anything you did in the --squirrel-install and
      // --squirrel-updated handlers

      // Remove desktop and start menu shortcuts
      spawnUpdate(['--removeShortcut', exeName])

      setTimeout(app.quit, 1000)
      return true

    case '--squirrel-obsolete':
      // This is called on the outgoing version of your app before
      // we update to the new version - it's the opposite of
      // --squirrel-updated

      app.quit()
      return true
  }
}

You might be wondering about the spawn code that is referenced in this sample. If you recall, Squirrel installs our app with the AppData folder. Unfortunately, it does not auto generate a shortcut for the user and place it on their desktop. That spawn code will do this as part of the install or update process. Our standard auto-update events will still be triggered, so we need to have the code in place to allow Squirrel to perform its tasks.

Generating Our First Build

With our app’s code updated to handle the Squirrel events and the url to check for any updates, let’s properly generate our application. From the terminal:

npm run dist

This process will take a few moments to complete. Once it has completed, go ahead and launch the xxx-setup.exe on a Windows machine. You should see your screen loading gif, then a shortcut created on the desktop. The auto-update check should also run (Figure 16-5).

Figure 16-5. The No Update dialog

Since we have not provided any update files, you will see a dialog informing you that no updates are available. So, let’s make an update!

Generating an Update

To properly generate an update and the associated files, we need to follow some simple steps. First, those three files that we generated for our first release need to be uploaded to the server that our auto update url is pointing to.

Second, we need to update the package.json file to inform Electron Builder where to reference our remote releases.

"squirrelWindows": {
      "iconUrl": "http://your-company.com/releases/win/icon.ico",
      "remoteReleases": "http://your-company.com/releases/win/",
      "loadingGif": "./build/loader.gif",
      "useAppIdAsId": false
    }

This url should be the same as our auto-update URL in our application code. Now when we build our new application, electron builder will use the files hosted there to generate our *-delta.nupkg file, as well as update the RELEASES file with the new data.

Finally, you need to update the version number in the package.json. If you want to make a simple change to the index.html, you can do that as well.

With those changes in place, execute the npm run dist command again. The process will take a bit longer as the remote files are accessed. When it is complete, we will have several new files alongside of the files from the first build:

• autoupdatedemo-1.0.0-full.nupkg

• autoupdatedemo-1.0.1-delta.nupkg

• autoupdatedemo-1.0.1-full.nupkg

• Electron Demo Setup 1.0.0.exe

• Electron Demo Setup 1.0.1.exe

• RELEASES

Upload these new files, along with the RELEASES file to the server. Once they have transferred, launch the application again on your Window machine. This time, there will be an update available (Figure 16-6).

Figure 16-6. The AutoUpdate dialog

Click the Update button, and the update will be downloaded for us (Figure 16-7).

Figure 16-7. The AutoUpdate Downloaded dialog

Once that is done, we can install it and relaunch our application. Our application is now up to date! You now have the framework in place to auto update your Electron application on Windows.

Alternative Solutions

Now, using Electron Builder is not the only option to create packaged Electron application. The Electron team also has a Windows installer module. The package can be found at https://github.com/electron/windows-installer . This module does expose more settings for your Squirrel instance. You might want to consider looking at this solution if your application needs additional parameters configured, like a custom-loading Gif.

Another option you might also explore is Electron Forge ( https://beta.electronforge.io/ ). Developed by the same team as Electron Builder, this project aims to be a single command-line interface for Electron. It supports packaging to a wide range of platforms. What is interesting is, it uses Electron’s Windows Installer for any Squirrel packages. This effort is very intriguing, and it could be a nice solution to for your Electron development workflow.

Finally, we want to touch on Electron Builder itself. If you spend some time reading the documentation, you might notice it has a section on auto updating. Instead of using Electron’s built-in Auto Update module, it instead relies on their own electron-updater module. There may be advantages to using this solution instead of the built-in solution, but you will need to make that call yourself.