Working with custom janus.js dependencies

Certain dependencies of janus.js may be passed during library initialization as a property list containing the following keys:

1. newWebSocket: a function which given WebSockets server and protocol arguments should return a new WebSocket (or something that acts like it)
2. webRTCAdapter: an adapter object such as provided by the webrtc-adapter library
3. isArray: a function which tests if a given argument is a JavaScript array
4. checkJanusExtension: a function which tests if the Janus Screensharing extension for Chrome is installed/available. This can be done by testing whether or not an element with an id attribute value of janus-extension-installed is present.
5. httpAPICall: a function which given an url and options argument performs an HTTP API request to Janus. This function is not as straightforward to implement, see the section on httpAPICall below for details.

Depending on your needs you do not have to provide all these dependencies, e.g. you do not need to implement the httpAPICall function if your application relies exclusively on WebSockets to access the Janus API.

Two implementations of the dependencies object are provided by janus.js:

1. Janus.useDefaultDependencies
2. Janus.useOldDependencies

In turn, each of these implementations accept their dependencies as arguments or fallback on certain global variables. Below follows an overview:

Janus.useDefaultDependencies

The Janus.useDefaultDependencies method relies on the following native browser APIs:

1. Promise: support for Promises as standardised in ES 6 (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises)
2. fetch: support for the fetch API (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
3. WebSocket: support for the WebSocket API (https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
4. document.querySelector: support for the document.querySelector API (https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)

Additionally the adapter object from the webrtc-adapter library is also required. These dependencies may either be passed explicitly to the function as a property list with keys of the same name, or if omitted the function will fallback to relying on global variables of that name instead.

Example:

        var customDependencies = Janus.useDefaultDependencies({
                fetch: myCustomFetchImplementation // myCustomFetchImplementation should provide a compatible fetch() API
        });

        var relyingOnGlobalsEntirely = Janus.useDefaultDependencies();

Being able to passe dependencies like this is especially useful in the context of modern ES modules:

import adapter from 'webrtc-adapter';
//  other imports elided

const setupDeps = () => Janus.useDefaultDependencies({
        adapter,
        // other dependencies elided
});

export const initialiseJanusLibrary = () => Janus.init({dependencies: setupDeps()});

Janus.useOldDependencies

The Janus.useOldDependencies method relies on:

1. jQuery: the JQuery library (http://jquery.com/)
2. WebSocket: support for the WebSocket API (https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)
3. adapter: the adapter object from the webrtc-adapter library

This function provides a simple upgrade path for existing applications which are heavily tied to jQuery (especially since previous versions of janus.js depended on it).

httpAPICall

The httpAPICall function is used to issue API calls to the Janus HTTP(S) interfaces. It will be passed two arguments:

1. url: a string which refers to the (server) URL of the API endpoint to contact
2. options a property list (see below)

Any return values from the httpAPICall function will be ignored.

When working with HTTP request or response bodies, the httpAPICall is responsible for serialisation to, and deserialisation from the 'wire format' (JSON). That is: the httpAPICall must transform objects to JSON or parse JSON as and when required. Similarly, the httpAPICall is also responsible for setting appropriate HTTP Content-Type (application/json) and/or Accept headers.

The options argument may contain the following keys:

1. timeout: a timeout in milliseconds which should be imposed on the request. The httpAPICall implementation is required to implement support for imposing timeouts on HTTP API requests.
2. body: payload to include as body of the outgoing HTTP request. The httpAPICall must encode it in the 'wire format' (JSON).
3. withCredentials: a boolean indicating whether or not HTTP credentials should be sent
4. success: a callback which should be dispatched when an API request was successful.
5. error: a callback which should be dispatched when an API request was unsuccessful, or timed out
6. async: a boolean hint which indicates whether or not asynchronous requests are desirable. This hint is a primarily a remnant for backwards compatible behaviour when working with jQuery.

The success callback should be passed the deserialised API response body. The error callback accepts two arguments: a descriptive status text string and the raw error object which caused the error callback to be invoked.

Note

The httpAPICall represents the primary way to intercept HTTP(S) API calls issued from within the janus.js library. You can use this mechanism to augment outgoing requests with additional headers or to intercept responses. For example:

1. You can support authentication schemes based on the HTTP Authorization header by injecting it into outgoing API requests and routing them through a proxy.
2. You can intercept incoming responses and extract data from custom header values generated by a proxy.
3. You can combine both to implement a robust defence against CSRF
4. You can reroute the control flow entirely, and e.g. use httpAPICall as an action creator in your Redux application.

Custom Screensharing Extension for Chrome

To use a different extension for screensharing permissions in Chrome you can pass a extension object to Janus.useDefaultDependencies and Janus.useOldDependencies. The object should provide the following methods:

1. init(): Do any setup work here. Will be called once when the dependencies are loaded.
2. isInstalled(): should return a boolean indicating whether the Extension was detected and is ready to use.
3. getScreen(callback): make a call to the extension to get a streamId here. The streamId can be obtained from chrome using chrome.desktopCapture.chooseDesktopMedia(). When the request is successful pass the streamId back using callback(null, streamId), otherwise pass an Error object like callback(error)