Construct can export your project as a macOS desktop app using WKWebView. This is basically a version of the Safari browser engine that is built in to macOS. In other words it's very much like having your project run in Safari, but without any browser parts like the address bar showing, so it looks like a traditional desktop app. It's also a very lightweight export option with minimal file size overhead as it does not need to bundle a browser engine. This tutorial covers how to use this export option.
See also:
WKWebView features
Construct is based on browser technology, but WKWebView 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
- WKWebView updates with macOS system updates, so you generally don't need to worry about updates for the browser engine.
- Some actions which are only allowed after a user input event, such as audio playback and entering fullscreen, 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
- If you enable a theme color in Project Properties, it will be used to tint the window caption
- You can use the File System plugin to directly access certain folders on disk - such as to read and write files directly to the user's Documents folder with the picker tag "<documents>". See the File System plugin manual entry for more details on that.
Exporting
Prerequisites
To publish a macOS app that is allowed to run on other systems, you'll need to sign the app, and that requires an Apple Developer account. You'll need to sign up with Apple and pay a fee. Note that if you've published to iOS before, you'll likely already have an Apple Developer account that you can also use for macOS publishing.
The macOS exporter requires that your project has a valid app ID set. Make sure the ID in Project Properties is filled out before exporting. Typically this is in reverse-domain format, e.g.: net.construct.kiwistory
Exporting options
When exporting to macOS, an options dialog will appear with some macOS-specific settings. These are described below.
- Use App Sandbox: enable the use of the macOS App Sandbox, which imposes tighter security restrictions on the app. This is a requirement for publishing to the Mac App Store, but may need to be disabled for other publishing platforms like Steam. Also note that when the App Sandbox is enabled, some file system operations may work differently - for example sandboxed apps effectively get their own unique 'Documents' folder, and don't share the same system 'Documents' folder that the user normally sees.
- Bundle assets: by default all your exported project files end up in a subfolder named www inside the app. It is possible inquisitive users could find some of your project's assets in here, including artwork, music and sound effects. If you enable Bundle assets, all these files are combined in to a single file named assets.dat. This file is not encrypted, but it does prevent casual browsing of the exported files. On modern systems, enabling this option should not significantly impact performance.
- Enable DevTools: whether to allow debugging the webview inside the app using Safari's developer tools. This is useful during development to view things like console messages, but you may want to disable it when publishing.
- Permissions: use the Edit button to select the permissions your app needs. If it tries to use something like camera input without the permission being enabled, it will be blocked from using it. Some permissions are only enforced when the App Sandbox is enabled, but it's a good idea to make sure these are all set correctly anyway. There are roughly three types of permissions:
- Camera and Microphone: whether the app can receive input through the user's camera and microphone (typically via Construct's User Media plugin). If these are enabled, for privacy reasons you must also provide a description of what the input is used for.
- Internet Server: whether the app is allowed to act as a server on the Internet (i.e. receiving incoming connections from other devices, instead of initiating outgoing connections as a client). Typically this should only be enabled if your project uses Construct's Multiplayer plugin, as this uses peer-to-peer connections and allowing server permission may improve connection quality.
- Pictures, Movies and Downloads folders: whether the app is allowed to read from, or both read and write, to these shared system folders. This is normally only needed if you use Construct's File System plugin to access these folders.
- Signing identity: macOS applications must be signed using an Apple developer account to be allowed to run on other systems. Construct can help make this easy for you if you enter the signing identity for your Apple developer account here, normally in the form Developer ID Application: Name (ABC123). See the section on signing and notarizing below.
Extracting the exported zip file
Once you export your project for macOS, Construct will generate a zip file. It's important to note that the zip must be extracted on macOS for the app to work properly. If you extract the files on Windows and then copy the files to a macOS device, the app won't work. This is because Windows and macOS understand file permissions differently, and some specific file permissions are required for the app to work. macOS understands these file permissions and so preserves them from the zip, but Windows does not, and so will remove the required file permissions when extracting.
Note that for security reasons, macOS will at first most likely prevent the app from running since it treats it as an untrusted app. You'll see a security warning and the app will not launch. To solve this you will need to sign and notarize the app - see the section on that below.
Signing and notarization
If you export a macOS app and try to immediately run it, macOS will show an error and block you from running the app. The reason for this is that modern versions of macOS require all apps to be signed before they can be run. Signing an app means applying a digital signature that verifies who it came from, and guarantees the app has not been tampered with since you published it. You should then also notarize the signed app. This means it is submitted to Apple who run an automated approval process that has further security benefits.
Advanced users may be comfortable referring to Apple's documentation and handling signing and notarization manually. However Construct exports some scripts to help make these steps easy, and most users will probably want to use them. You can run these scripts by double-clicking them in macOS's Finder. Construct exports the following scripts alongside your app:
- sign-adhoc.command: run this to add an ad-hoc signature to the app. This essentially means the app will be allowed to run on your system only. It's a useful option for testing and development, but you can't use this for distributing your app.
- sign.command: run this to sign the app with the Signing identity you provided on export. Note if you leave that field empty, then this script is not exported.
- setup-notarize.command: before you can run notarize.command, you must run this setup script to provide some information about your Apple developer account. Follow the instructions in the prompt to provide these details. The information is remembered on the system, so you only need to run this once per system, or if your Apple developer account details change.
- notarize.command: this submits your app for notarization. You must have run the setup-notarize.command script on the system previously for this to work. The notarization process may take a while, as it will upload your app to Apple's notarization service, and then wait for the automated checks to complete. This script also performs stapling, which means notarization verification is also available for users who are offline.
The file entitlements.plist is based on your export options and is used for the signing process. Once signing and notarization is complete, you don't need any of these files any more - you can distribute the .app bundle alone.
Diagnosing issues
A useful tool to diagnose the status of signing and notarization for an app is a third-party tool Apparency. Please note this is a third-party tool and so Scirra are not responsible for it and you'll need to contact the app developers for support.
Distribution
The exported app only uses features built in to macOS, so it does not require anything else to be installed. The minimum supported version of macOS is macOS 12 (Monterey), so that version and all newer versions of macOS are supported.
The browser engine used by the app, called WKWebView, is provided by the macOS system. It is based on the version of Safari that originally shipped with macOS. For example macOS 12 originally shipped with Safari 15, and so WKWebView on macOS 12 is always based on Safari 15.x. It will be updated to newer versions of Safari 15, such as Safari 15.4, 15.6, etc. However if the system updates Safari to version 16 (a new major version), it will not update WKWebView on that system, which remains on version 15.x. The only way WKWebView updates to a new major version is via macOS system updates. For example WKWebView on macOS 13 (Ventura) is based on Safari 16, and so on. (To help you remember the versions, note that the WKWebView version is three ahead of the macOS version.)
The exported app supports both Intel and Apple Silicon devices with a universal binary. This means it should run on both kinds of chips without any kind of emulation or performance penalty.
Conclusion
The macOS wrapper export option provides a lightweight option for publishing to macOS, using a system-provided webview to power your project. It's a convenient option since it has a low file size and doesn't require setting up web hosting. Remember to sign and notarize your app before broader distribution.