# Getting started

# Installing BetterTouchTool and setting up webserver

# For new BetterTouchTool users

To get started - install BetterTouchTool from here. If you need help visit community forum.

# For existing BetterTouchTool users

If you have already installed BTT and you did not configure webserver yet - you can simply import the config via visiting a link and confirm the prompt that'll pop up: click here to import default webserver config

If you have webserver already configured - you'd need to configure it as follows so the rest of this guide works well for you. Please override the window.config variable to match your config if you want use the guide any further, for example, in devtools:

window.config = {
  domain: '127.0.0.1',
  port: '8888',
  protocol: 'https',
  sharedKey: 'ABCDEFGHIJKLMNOPRSTUVWXYZ',
};

The changes will get saved to your localStorage on current website, so you won't have to update the config for each page of the guide.

# Testing it out

Alright! Time to verify whether you made it work 😃 Try to play with btt instance in devtools, for example:

btt.showNotification({title: 'Okay!', content: 'It works 🎉'}).invoke();

Works? Great! If not, please verify your config and ensure that BetterTouchTool is running (restart may be required after changing webserver config).

# Staying secure

# Use https

BetterTouchTool allows you to set up an https certificate for the webserver - you will need to trust BetterTouchToolRemote_new certificate in your keychain to prevent errors in your browser.

HTTPS prevents intruders from being able to passively listen to communications between your websites and your users (you in that case).

# Use shared key

As an additional security measure, BTT allows you set up a shared key which is stored in your Apple Keychain under the hood. Definining it allows to invoke only the GET requests which includes &shared_key=YOUR_KEY parameter. Combining this with other ways to stay secure allows you to be pretty much secure on the web.

# Change the default port

Network protocols can be defined in range 0-65535 - however, ports from 0 to 1023 are considered as well known ports, and are used to and identify the historically most commonly used services.

Basically, any port that you set up in range between 1023 - 65535 should work - if you want you can look up the list of tcp and udp port numbers to make sure you do not interfere with other technologies.

# Listen on specific IP

By default, BTT webserver is only accessible from localhost (127.0.0.1) which is good - because no one will be able to connect to you from you local LAN network. But due to fact that you can visit any website which someone sends - and this website can access your localhost then, because you're visiting it from your computer - sometimes it might be a better idea to set up a static IP address in you LAN to secure yourself from websites that may want to exploit the fact that you're using localhost listening only.

Surely, it makes you accessible through LAN - but pretty much ensures that no website will be able to communicate with your webserver at all, if you don't want to.

# Set up blacklist of actions

btt.js allows you to set up a blacklist of actions that will not be performed upon calling it.

You can use btt-node-server as a specific middleware for calling your actions, and blacklist every action that you don't want to perform (for example executeScript or lockScreen). For more, see configuration section.

You can edit this page on GitHub.