Using the ServiceHandler

ServiceHandler is the helper global object for connecting to the Captivate API server.

init method

Initializes the connection to the Captivate API server.

// when you want the ServiceHandler to automatically determine the best connection method, use this call.
ServiceHandler.init();

// when you want to use a specific websocket url, initialize with a call like this.
ServiceHandler.init(serverUrl);

// when you want to use a pre-existing websocket or any other socket connection (useful when calling from nodejs),
// you may pass the socket as the second argument. The socket must implement at least the `onmessage` and `send`
// methods like the native browser JavaScript WebSocket for sending and receiving messages and for closing connections.
ServiceHandler.init(null, socket);

Arguments

• serverUrl - (optional) URL of the web socket server to use for communication with Captivate. When the script is hosted by the built-in Captivate HTTP server, this argument isn’t needed because Captivate will put its own connection information into a cookie served with the main page. However, if you are hosting your HTML page on another server, you might need to specify this value manually. The url should look like this ws://CAPTIVATE_COMPUTER_IP:CAPTIVATE_PORT.

  • CAPTIVATE_COMPUTER_IP: The hostname or local IP address of the computer running Captivate.

  • PORT: The port Captivate exposes for API communication. Captivate defaults to using port 9023 for the WebSocket API.

    • Changing the webSocket port is possible by editing the NewBlue settings in the Windows Registry or the Mac Preferences.

    • Mac: defaults write com.newblue.captivate 'Generic HTML.webSocketPort' 10002 (from ~/Library/Preferences/com.newblue.captivate.plist)

    • Windows RegEdit: \HKEY_CURRENT_USER\SOFTWARE\NewBlue\Captivate\Generic HTML.httpPort

    • The main HTTP server port can also be read/set using the Generic HTML.httpPort key.

  • To avoid hardcoding this value in your scripts, you can also specify the host and port using a query string in your browser’s url like this: ?ip=127.0.0.1&port=9023. The ServiceHandler object will automatically look for those values if a serverUrl is not provided.

• socket - When you are running in nodejs or in some other context, you might have a previously negotiated socket compatible with the JavaScript WebSocket interface. You can pass that socket directly to the ServiceHandler as the second argument, specifying the first one as null.

About the automatic connection method

When init is called with no arguments and the ServiceHandler is running in a browser context, the library will attempt to connect with Captivate using a number of different connection methods:

1. ServiceHandler will gather some default values from the URL query parameters:

• It will use ip or hostName for the websocket domain (defaults to the domain of the browser url).

• It will use port as the websocket port (defaults to 9023).

• It will use wsTunnel as the unique identifier for a remote websocket tunnel (see below).

• Captivate will automatically add these query parameters to any data controller it hosts.

1. ServiceHandler will attempt to make the following connections:

• First, it will try to connect to ws://[ipOrHostName]:[port] (specified in the url)

• Second, it will try to connect to ws://127.0.0.1:[port] (always tries localhost)

• Third, it will try to tunnel its websocket connection through NewBlue’s secure websocket tunnel: wss://controllers.newbluefx.com/tunnel/[wsTunnel]/client

• Fourth, if the browser has WebRTC capabilities, ServiceHandler will use the NewBlue tunnel to negotiate a direct secure peer-to-peer connection to Captivate through WebRTC. If a WebRTC connection can be established, it will replace the websocket tunnel connection resulting in a direct connection that doesn’t pass through any NewBlue servers.

Example:

<script src="https://newbluefx.com/api/v3/common/js/qwebchannel.js"></script>
<script src="https://newbluefx.com/api/v3/common/js/servicehandler.js"></script>

<script>
  const cleanups = [];
  const cleanup = () => {
    for (const fn of cleanups) {
      fn();
    }
    cleanups = [];
  };

  // Will attempt to auto-connect.
  ServiceHandler.init();

  ServiceHandler.onready = async () => {
    // The `ServiceHandler.scheduler` object is ready now.
    // Note: webRTC connections take longer to set up, so if one
    // ends up being used, this function might be called a second time.
    // Always make sure to set up your signal connections here.
    cleanups.push(ServiceHandler.scheduler.onNotify.connect(console.log));

    // optional, but you should notify the backend who you are.
    const serverStats = await ServiceHandler.scheduler.notifyClientConnected('My Input Name');

    // serverStats will be an object like this (for more detail, use the `getReport` command)
    // {
    //   "buildDate": "Jan 27 2026",
    //   "buildTime": "09:31:17",
    //   "host": "TitlerLive",
    //   "licensed": "true",
    //   "platform": "macos",
    //   "product": "Captivate",
    //   "sku": "SKUTL5BR",
    //   "version": "2025.0.260127"
    // }
  };

  ServiceHandler.onerror = () => {
    // handle connection failure messages
  };

  ServiceHandler.onclose = () => {
    // handle connection close here
    cleanup();
  };
</script>

scheduler property

Scheduler API object. Will be undefined until the ServiceHandler.onready callback fires.

Usage:

// The ServiceHandler.scheduler object will exist as soon as the ServiceHandler object exists
// but calling functions on it will output warnings to the console and resolve to error messages
// until Captivate is connected as if you called a non-existent function
const result = await ServiceHandler.scheduler.getCookies();
// {
// 	"success": false,
// 	"error": "Method not found. Either we have lost connection to Captivate, or the installed version doesn't support this API method."
// }

Using promises instead of callbacks...

The scheduler object exposes all of its functions in a way that allows callbacks or promises, but they operate differently. The callback method is the older method and will always call the callback with the string content of the scheduler response.

To provide a callback to any scheduler function, simply include it as the last argument of the function.

However, if a callback function is not provided, the scheduler will automatically switch to using the Promise method and you can use await or .then() / .catch() functions to access the return value.

Finally, if a function is not exported by the current Captivate API, it will not throw an exception, but will instead respond with a failure message as described above.

console.log(await ServiceHandler.scheduler.hello());
/*
{
    "success": false,
    "error": "Method not found. Either we have lost connection to Captivate, or the installed version doesn't support this API method."
}
*/

serverUrl property

Websocket server URL currently used to communicate with Captivate (i.e. ws://localhost:9023).

Usage:

ServiceHandler.onready = () => {
  console.info('ServiceHandler connected to', ServiceHandler.serverUrl);
};

onready callback

Executes when connection to server is established.

Usage:

ServiceHandler.onready = () => {
  console.info('ServiceHandler connected');
};

onclose callback

User callback to execute when connection to server is terminated.

Usage:

ServiceHandler.onclose = () => {
  console.info('ServiceHandler disconnected');
};

onerror callback

User callback to execute when an error is encountered trying to communicate with the server.

Usage:

ServiceHandler.onerror = (e) => {
  console.error('ServiceHandler error', e);
};

Using the ServiceHandler.scheduler Object

All API actions happen with methods defined on the scheduler object. The scheduler object directly exposes these functions from the C++ environment to the JavaScript environment; however, only a few methods are relevant for data controller developers and those are documented here.

In each case, whenever a ‘return’ value is described, it will be passed as the sole argument (as a JSON-encoded string) to a callback function or will be the value of the resolved promise if no callback function is supplied. Additional functions for using the scheduler object can be found on the subsequent pages.