Loading Required JS Files

HTML/JavaScript Data Controllers communicate with Captivate over a WebSocket connection made possible with two helper library files. Make sure you include these files in your HTML (they are available in the common subfolder of the Service Handlers/HTML folder).

<!-- When hosted by Captivate -->
<script type="text/javascript" src="../common/js/qwebchannel.js"></script>
<script type="text/javascript" src="../common/js/servicehandler.js"></script>

Note: Technically, you don’t need either. Our primary API communicates in plain text over an unsecured websocket connection, but the qwebchannel.js script wraps that communication to allow sending type-safe data and to call native methods from JavaScript. servicehandler.js is our own custom wrapper for qwebchannel.js that manages the websocket connection and provides an easier API.

If you are hosting your HTML page somewhere else, you can also reference these files directly from our website:

<!-- Using our CDN -->
<script src="https://newbluefx.com/api/v3/common/js/qwebchannel.js" type="text/javascript"></script>
<script src="https://newbluefx.com/api/v3/common/js/servicehandler.js" type="text/javascript"></script>

If you want to use this library from the context of a JavaScript module, you only need this:

<script type="module">
  // When called as a module like this, the ServiceHandler module loads qwebchannel internally
  import { ServiceHandler } from 'https://newbluefx.com/api/v3/common/mjs/servicehandler.js';
</script>

Note about Security: The communication between JavaScript and Captivate happens over a plain-text websocket connection. As a result, if you are hosting your controller on an HTTPS server, most browsers will block connections to Captivate as “insecure” unless the browser running the controller is on the same computer as Captivate. The ServiceHandler library will automatically attempt to work around these browser limitations by trying a series of connections in order. See more in the description of the init function on the next page.

Note about oAuth: Some providers like Google don’t like doing oAuth from within the context of an embedded browser like the one running inside Captivate. As a result, you might need to open a system browser that will eventually pass data back to Captivate through the API or some other means. To construct a link that will open in the system browser, you can use browser:// as the scheme, or you can use the openUrl command.