Loading...
Searching...
No Matches
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)`