Home Projects Blog


Back to WebBLE project page

How do I debug my web page running in WebBLE?

The answer depends on whether you have bought WebBLE from the App Store or have built it yourself. If you have built it yourself you can attach Safari's Web Inspector to it which gives you a lot of tools. Unfortunately it is not possible to use Safari's Web Inspector on WebBLE bought from the App Store.

App Store tips

Develop first using Chrome or similar on a Mac / PC to get it working and use the debug tools there.

Once on your iOS device, you can hack console.log() and use window.addEventListener('error', <handler>) on your web page to log logs and errors to, for example, a console style <div>.

Locally built development version

You need to configure your iOS device and your Mac to allow Safari on your Mac to connect to WebBLE on your device and inspect the web page running in WebBLE. (The same method is used to debug web pages running in Safari on your device.)

Apple's instructions for this are here, but in essence these are:

  1. Connect your device by lightning/USB to your Mac.
  2. In Safari's section of the Settings app on your device:
    1. Disable Private Browsing if enabled.
    2. Enable the Web Inspector in the Advanced section.
  3. In Safari on your Mac:
    1. Enable Safari's Develop Menu in the Advanced pane of the Preferences panel (Cmd + ,).
    2. Select the web page to inspect from the Develop -> iPhone menu in Safari.

How do I use my self-signed certificate with WebBLE?


Security is a big issue for bluetooth devices, and the Web Bluetooth spec is clear that it expects Web Bluetooth-using sites to be secure HTTPS sites. WebBLE follows this advice strictly and so only allows connections to HTTPS sites.

While this is fine for using published sites, it can be a bit of a pain for sites that you are developing locally. You have two main options:

  1. download the source code for WebBLE and build and run it yourself with overrides of the default security policy to allow access to HTTP sites or
  2. use a self-signed certificate.

The following steps are for option 2, and assume you have already created a self-signed certificate to use and have configured your webserver to use it. Both of those steps are outside of the scope of this doc, but you can find excellent instructions on creating your own self-signed certificates on the httpwatch.com blog.


The essence of this is that you need to install the certificate on your iOS device and then configure it to trust the certificate system-wide.

  1. Create your self-signed certificate and key files using openssl or however. Be sure it has the correct /CN “Common Name” for your local server, e.g. mycomputer.local. The httpwatch blog post will help with that.
  2. Configure your webserver to use it (obviously) and check that it is.
  3. Email your certificate to an email address you can access on your iOS device.
  4. Tap on the attachment in Mail on your iOS device, this should now prompt you to install it. Do so.
  5. You should now verify that it is installed by going to the Settings app then General -> Profile -> <Common Name>. The Profile menu probably won’t be there at all until you’ve installed the first certificate. The certificate should be marked Verified <tick> (it was verified by you when you installed it).
  6. You might, like I did, have thought this would be enough. It isn’t. You now, really counter-intuitively, need to go to the setting General -> About -> Certificate Trust Settings and enable full trust for your certificate there as well. It’s such a weird place for that setting to be.

Now you should be able to use WebBLE to navigate to your site https://mycomputer.local.

Copyright 2018 David Park