Skip to main content

Build, Test and Install a Plugin

You build a plugin on your own computer, pack it into one JSON file, and install that file on your exchange from Operator Controls. You don't need access to the exchange's servers.

What you need​

  • The Enterprise plan on HollaEx Cloud, to install plugins.
  • Node.js and npm on your computer.
  • An exchange operator account that can open Operator Controls → Exchange → Plugins.
  • An HTTPS host for any website files your plugin loads, such as a Site Studio frame or a Kit v2 Web bundle.

1. Start from the starter​

The public HollaEx plugin starter has a working example, hello-exchange, and the build script that packs a plugin into its JSON file. Each plugin is a folder with:

  • config.json: the plugin's name, version, author, descriptions, settings (meta and public_meta) and libraries (prescript.install). See How plugins work for each field.
  • script.js: the server script, if the plugin has one.
  • web_view.json: the Kit v2 Web views, if any.

Copy hello-exchange, rename the folder and the name field, and build from there.

The starter dates from 2021

It covers the server script, settings, libraries and Kit v2 Web views. It predates declarative admin views, Site Studio manifests and secret: true settings. You can still add secret: true to any setting in config.json. For the current admin view and Site Studio formats, open a ticket.

2. Develop​

  • Server script. Write your endpoints under /plugins/<plugin-name>/. Read settings from meta and publicMeta, and check every required setting when the script starts. Keep provider calls and business logic in plain functions so you can unit test them on your computer.
  • Settings. Give every setting an operator-friendly description, and mark every credential secret: true.
  • Website views. A Site Studio frame is an ordinary web page served over HTTPS. A Kit v2 Web view is a React bundle; the starter's web folder has a local development server for it.
  • Fail closed. When a setting is missing, a signature doesn't verify or a provider can't be reached, reject the request or hold the action, and log why.

3. Build the plugin JSON​

Run the starter's build for your plugin. It minifies the server script and writes <plugin-name>.json in the plugin's folder, with config.json, the script and the views packed into one file.

Upload any website files your plugin loads before you install it. The plugin JSON points to them by URL, and a URL that doesn't answer shows as a broken view on your exchange.

4. Install it on your exchange​

  1. Go to Operator Controls → Exchange → Plugins and click Add plugin.
  2. Upload your JSON file, or enter the URL of the JSON file.
  3. Read the warning and confirm by typing I UNDERSTAND. The exchange reloads its plugins.
  4. Open the plugin, go to its Configuration tab, fill in the settings and save.

See Install and manage plugins for enabling, disabling, restarting and removing plugins.

5. Test​

Test on your exchange once the plugin is installed and configured:

  • Call each endpoint, including with missing or wrong input, and check that it refuses what it should.
  • If the plugin receives webhooks, send a test event from the provider's dashboard.
  • Check the Admin view tab, if your plugin has one, and the pages, blocks or steps it adds to your website.

Installing, updating and saving settings reload every plugin on the exchange, which briefly interrupts all of them. Plan your testing for a quiet time.

6. Ship an update​

  1. Raise version in config.json. The exchange refuses an update with the version that is already installed.
  2. If a website file changed, upload it under a new, versioned file name and point the plugin at the new URL. The installed version keeps working with the old file until you upgrade.
  3. Build the plugin JSON again.
  4. In Operator Controls → Exchange → Plugins, open the plugin, open the more-actions menu, choose Upgrade from file and upload the new JSON file.

The operator's saved settings are kept for every setting that still exists in the new version. A Site Studio manifest is replaced, so a version that drops a page or block removes it from the website.

Treat a plugin like code with full access

Operator Controls shows the same warning for every plugin file, whoever the author says it is. A plugin can read and change user data and balances, move funds and use your API keys. Install a plugin only if you built it, or you know who did and have reviewed its code. Never install a plugin file someone sent you unexpectedly.

Need help? Open a ticket from your HollaEx dashboard.