Exporting to Windows with the WebView2 wrapper

5

Stats

866 visits, 1,160 views

Translations

This tutorial hasn't been translated.

Tools

Construct can export your project as a traditional Windows desktop app using Microsoft Edge WebView2. This is basically a copy of the Microsoft Edge browser engine that is built in to Windows. Note Microsoft Edge is based on the same Chromium browser engine as is used by Chrome. In other words it's very much like having your project run in Edge or Chrome, but without the user needing to have a specific browser installed on their computer, and without the browser parts showing like the address bar so it looks like a native app. Also since the exported files don't need to include a full browser engine (like NW.js does), it's a very lightweight export option with minimal file size overhead. This tutorial covers how to use this export option.

NW.js also provides a way to export a Windows desktop app. You can find out more about how it compares to the Windows wrapper in the tutorial Comparison between NW.js and Windows wrapper.

Exporting

When exporting, you can choose some options in the Windows Wrapper options dialog. This includes choosing which of the platform architectures you export for, which includes:

  • 32-bit (x86): for Windows 32-bit on Intel-compatible systems
  • 64-bit (x64): for Windows 64-bit on Intel-compatible systems
  • ARM64: for Windows 64-bit on ARM-based systems

The Intel-compatible Windows 64-bit is the most common version of Windows, but you can support more systems by distributing all the platform-specific versions of the app.

Architecture naming

The names of the architecture may look odd, but they are the technical terms used in the software industry.

Although the x64 architecture is 64-bit, the x86 architecture is 32-bit, not 86-bit. The x86 name derives from the Intel 8086 microprocessor, which was actually originally 16-bit. However later chips were 32-bit and replaced the older 16-bit kinds. So "x86" is now widely used to refer to the 32-bit instruction set of Intel-compatible processors. See x86 on Wikipedia for more history.

Try not to confuse x64 with ARM64: both are 64-bit systems, but they are for different chip architectures (Intel-compatible and ARM respectively). ARM is used for some newer battery-powered devices such as the Surface Pro X.

WebView2 features

Construct is based on browser technology, but WebView2 does not work exactly the same as a browser. Some of the differences of most interest are:

  • Lightweight export option that does not need to include a copy of an entire browser engine, relying on the system instead
  • WebView2 automatically updates, much like modern browsers, ensuring users get the best performance and latest features
  • Permission requests, e.g. for the camera, are automatically approved without prompting the user.
  • Some actions which are only allowed after a user input event, such as audio playback, can be used unrestricted
  • Navigating to a URL, or opening a URL in a new window, will open the system default browser. This could be a different browser entirely, e.g. Firefox.
  • The Browser 'Close' action exits the app
  • Accessing the browser developer tools can be disabled

Distribution

The exported app requires the Microsoft Edge WebView2 runtime to be installed. However if it is not installed, the app will automatically download and install it, and then should start up successfully. This only needs to be done once per system, and then the WebView2 runtime automatically keeps itself up-to-date, like modern browsers do. Microsoft also say future versions of Windows should come with the Microsoft Edge WebView2 runtime already built-in.

Advanced users can still include a full copy of a browser engine with the app if they choose to. This is referred to as "fixed" mode, whereas using the auto-updating system webview is referred to as "evergreen" mode. See the following section for more details.

If you can, you should also digitally sign your app. This will show that you are its verified publisher, and increases the trust the system has in your app. Without it, users may see warnings that the app is not verified or trusted, and some other security tools may treat it with enhanced caution.

Advanced topics

While the exported app ought to work straight away if distributed to users, these topics may be of interest to advanced users.

Customizing messages

When the user is prompted to install the WebView2 runtime, the app will show some messages, such as "This app requires the Microsoft Edge WebView2 runtime. It will be downloaded and installed for you now." You can customize these messages, such as to translate them, or explain in more detail what your app is doing. These messages can be edited in the "messages" section of the exported package.json file.

App icon

The exported executable shows with an icon from your project while running, but in Windows Explorer it will show with a stock icon. For technical reasons it's difficult for Construct to change this for you. However you can use third-party tools to change the icon of an executable. There are third-party tools available that can edit the icon of a Windows executable which you should be able to find by searching the web. For example one such tool is Resource Hacker.

Digital signature

The exported app is not digitally signed. This means it may show a warning when run for the first time. Other security tools may also treat it with enhanced caution.

To improve the level of trust the system has in your app, and avoid users seeing such warnings, you should digitally sign the app. This requires obtaining a code-signing certificate and using a Windows tool to sign the app with your certificate. This is a somewhat complex topic out of the scope of this tutorial, but you can start at the Microsoft documentation's Introduction to code signing, which includes the SignTool for signing executables, and search the web for further resources.

Sample signtool command

Once you have obtained a code signing certificate, got signtool.exe from the Windows SDK, and updated the executable icon if you wish to change it, the following PowerShell command illustrates how to sign your app's executable.

./signtool.exe sign /f "MyCodeSigningCertificate.pfx" /p CERTIFICATE_PASSWORD /t http://timestamp.digicert.com /d "My app description" /du https://www.example.com "MyAppExecutable.exe"

Note you should replace "MyCodeSigningCertificate.pfx" with the filename of your code signing certificate, CERTIFICATE_PASSWORD with the password for the given code signing certificate, "My app description" with your own description of your app, https://www.example.com with your own website URL, and "MyAppExecutable.exe" with your app's executable file.

Creating an installer

If you create an installer for your app, you can also make the installer pre-install the Microsoft Edge WebView2 runtime, so the app will work immediately on the first run and not have to prompt the user to download and install the runtime.

You can find standalone installers for the WebView2 runtime at the Microsoft Edge WebView2 website. You can then configure your installer to also run the WebView2 standalone installer during installation.

Fixed distribution mode

We recommend using the "evergreen" distribution mode, which is the default. This uses a system-provided webview that automatically updates. However it's possible to also ship your own copy of the Microsoft Edge WebView2 runtime with the app (similar to how NW.js works). This substantially increases the file size and will not update the browser engine automatically, so your app will remain on the same version until you release an update with a newer version.

To use fixed distribution mode, follow these steps:

  1. Edit package.json and change the value by "distribution-mode" (under "settings") from "evergreen" to "fixed".
  2. Create a subfolder in the same folder as your executable named webview2.
  3. Visit the Microsoft Edge WebView2 website and download a fixed version of the WebView2 runtime (with a specific browser engine version). Make sure you match the same architecture as the app that was exported.
  4. Extract the downloaded fixed version to the "webview2" subfolder. In the documentation for fixed mode, Microsoft advise to use the command line expand {path to the package} -F:* {path to the destination folder} or use a third-party tool such as WinRAR. They advise against decompressing through the File Explorer, as it may not generate the correct folder structure.
  5. Now run the app executable, and it should run successfully with the fixed version you downloaded.

Note in fixed mode, the app will never prompt the user to download and install the Microsoft Edge WebView2 runtime - it always uses the version in the "webview2" subfolder, and will fail to start up if there isn't a fixed version there.

Conclusion

The Windows wrapper export option provides a lightweight option for publishing to Windows, using an auto-updating system webview to power your game. It's a convenient option since it has a low file size and doesn't require setting up web hosting. Remember to distribute copies of your app for each system architecture (x86, x64 and ARM64), and advanced users should consider digitally signing the app.

  • 6 Comments

  • Order by
Want to leave a comment? Login or Register an account!
  • Is there an app store specifically set up for WebView2 apps yet?

  • could this replace NWjs for a Steam release? are there any performance differences?

      • [-] [+]
      • 2
      • Ashley's avatar
      • Ashley
      • Construct Team Founder
      • 2 points
      • (1 child)

      Steam integration is not currently supported in WebView2, but it's possible it could be in future. For performance, as ever measurements are the way to test that, but I would not expect there to be any significant difference as both NW.js and WebView2 are based on the same Chromium browser engine.

  • Finally Windows is doing this!

  • Excellent addition to Construct 3, I am very happy to see the evolution being closely monitored by the engine devs.

    I'm already testing and enjoying the results.