Exporting to macOS with the WKWebView wrapper

6

Features on these Courses

Stats

1,424 visits, 2,076 views

Translations

This tutorial hasn't been translated.

Tools

License

This tutorial is licensed under CC BY 4.0. Please refer to the license text if you wish to reuse, share or remix the content contained within this tutorial.

Construct can export your project as a traditional 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 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.

Exporting

Currently, there are no export options specific to the macOS WKWebView export option. However 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 notarize the app - for more details see the Distribution section below.

Locally testing an unsigned app

The security restrictions on macOS can be worked around for local testing only. This gets the app to work on one specific device, but it still won't work on other devices - as mentioned you'll need to notarize the app for wider distribution. However these steps can help with testing.

Apple Silicon devices

On devices with Apple Silicon, such as the M1 chip, the app must be signed otherwise macOS will refuse to run it at all. It's possible to use an ad-hoc signature to just get it working on one device.

You must apply the ad-hoc signature before attempting to run the app. It seems macOS remembers if an app is not valid and will permanently refuse to run it if any kind of error occurs. So run the command below before even trying to run the app. If you tried to run the app already, try renaming the app, which seems to reset the state that macOS remembered.

Open a terminal to the folder with your exported app (extracted from the zip) and run the following command to apply an ad-hoc signature:

codesign --force --deep -s - myexport.app

Now the app has a signature that will work for your device only. The next step should now work.

Bypass security check (all devices)

There are two ways to bypass macOS's security checks that by default prevent you running an unrecognized app.

  1. Hold control and click the app in Finder, and select Open from the menu. You may need to do this twice.
  2. After attempting to run the app and seeing a security message, open System Preferences, and go to the Security & Privacy section. You should see a message there indicating that an app was blocked, and there should be a button that says Open anyway. Click that button and the app should then launch, and be unblocked from running on that specific device.

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

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 10.14 (Mojave), 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. This means installing a newer version of Safari on a macOS system does not update the browser engine used by WKWebView. For example macOS 10.14 originally shipped with Safari 12, and so WKWebView on macOS 10.14 is always based on Safari 12, regardless of whether the Safari browser updated to a newer version. The only way WKWebView updates is via macOS system updates. For example WKWebView on macOS 10.15 (Catalina) is based on Safari 13, and so on.

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.

Notarize your app

As mentioned in the Exporting section, before publishing your app you will need to notarize it so other people can run it. For more information refer to Apple's documentation on Notarizing your app before distribution.

If you just want to test the app locally or otherwise want to skip notarization, you can work around the security restriction using System Preferences as described in the Exporting section.

Conclusion

The macOS wrapper export option provides a lightweight option for publishing to macOS, using a system-provided 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 notarize your app before broader distribution.

  • 5 Comments

  • Order by
Want to leave a comment? Login or Register an account!
  • My MacOs app has been refused by apple because the red interface button does not close the app, but only the Window. How can i disable the red button or close the whole app with it?

  • My MacOs app has been refused by apple because the red interface button does not close the app, but only the Window. How can i disable the red button or close the whole app with it?

  • MacOs users need to Unzip it then double click the .app file to run it right?

  • Hello,

    I am getting an error that "your browser does not support or blocks cookies"

    Is there a workaround for this or i am missing something?

    I would like to report that i cannot do the advance minify (the simple one works)

    Error exporting: minify-error

    Shb main.js:2122

    4dc93fd61-5602-45c6-af8b-f8a2ad5496cf:2416 Run main for com/google/javascript/jscomp/CommandLineRunner

    cheerpOS.js:1531 /str/main.js:141:423: ERROR - [JSC_UNDEFINED_VARIABLE] variable RuntimeInterface is undeclared

    141| const exportType=e["exportType"];if(exportType==="windows-uwp"&&typeof Windows!=="undefined")Windows["System"]["Launcher"]["launchUriAsync"](new Windows["Foundation"]["Uri"](url));else if(self["cordova"]&&self["cordova"]["InAppBrowser"])self["cordova"]["InAppBrowser"]["open"](url,"_system");else window.open(url,tag)}}_OnRequestFullscreen(e){if(this._exportType==="windows-webview2"||this._exportType==="macos-wkwebview")...

    Regards